
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>setuptools 46.1.3 documentation</title>
    <link rel="stylesheet" href="_static/nature.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" type="text/css" href="_static/_static/css/badge_only.css" />
    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="_static/language_data.js"></script>
    <link rel="search" title="Search" href="search.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="nav-item nav-item-0"><a href="index.html#document-index">setuptools 46.1.3 documentation</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="welcome-to-setuptools-documentation">
<h1>Welcome to Setuptools’ documentation!<a class="headerlink" href="#welcome-to-setuptools-documentation" title="Permalink to this headline">¶</a></h1>
<p>Setuptools is a fully-featured, actively-maintained, and stable library
designed to facilitate packaging Python projects, where packaging includes:</p>
<blockquote>
<div><ul class="simple">
<li>Python package and module definitions</li>
<li>Distribution package metadata</li>
<li>Test hooks</li>
<li>Project installation</li>
<li>Platform-specific details</li>
<li>Python 3 support</li>
</ul>
</div></blockquote>
<p>Documentation content:</p>
<div class="toctree-wrapper compound">
<span id="document-setuptools"></span><div class="section" id="building-and-distributing-packages-with-setuptools">
<h2><a class="toc-backref" href="#id3">Building and Distributing Packages with Setuptools</a><a class="headerlink" href="#building-and-distributing-packages-with-setuptools" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">Setuptools</span></code> is a collection of enhancements to the Python <code class="docutils literal notranslate"><span class="pre">distutils</span></code>
that allow developers to more easily build and
distribute Python packages, especially ones that have dependencies on other
packages.</p>
<p>Packages built and distributed using <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> look to the user like
ordinary Python packages based on the <code class="docutils literal notranslate"><span class="pre">distutils</span></code>.</p>
<p>Feature Highlights:</p>
<ul class="simple">
<li>Create <a class="reference external" href="http://peak.telecommunity.com/DevCenter/PythonEggs">Python Eggs</a> -
a single-file importable distribution format</li>
<li>Enhanced support for accessing data files hosted in zipped packages.</li>
<li>Automatically include all packages in your source tree, without listing them
individually in setup.py</li>
<li>Automatically include all relevant files in your source distributions,
without needing to create a <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> file, and without having to force
regeneration of the <code class="docutils literal notranslate"><span class="pre">MANIFEST</span></code> file when your source tree changes.</li>
<li>Automatically generate wrapper scripts or Windows (console and GUI) .exe
files for any number of “main” functions in your project.  (Note: this is not
a py2exe replacement; the .exe files rely on the local Python installation.)</li>
<li>Transparent Cython support, so that your setup.py can list <code class="docutils literal notranslate"><span class="pre">.pyx</span></code> files and
still work even when the end-user doesn’t have Cython installed (as long as
you include the Cython-generated C in your source distribution)</li>
<li>Command aliases - create project-specific, per-user, or site-wide shortcut
names for commonly used commands and options</li>
<li>Deploy your project in “development mode”, such that it’s available on
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, yet can still be edited directly from its source checkout.</li>
<li>Easily extend the distutils with new commands or <code class="docutils literal notranslate"><span class="pre">setup()</span></code> arguments, and
distribute/reuse your extensions for multiple projects, without copying code.</li>
<li>Create extensible applications and frameworks that automatically discover
extensions, using simple “entry points” declared in a project’s setup script.</li>
<li>Full support for PEP 420 via <code class="docutils literal notranslate"><span class="pre">find_namespace_packages()</span></code>, which is also backwards
compatible to the existing <code class="docutils literal notranslate"><span class="pre">find_packages()</span></code> for Python &gt;= 3.3.</li>
</ul>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><strong>Table of Contents</strong></p>
<ul class="simple">
<li><a class="reference internal" href="#building-and-distributing-packages-with-setuptools" id="id3">Building and Distributing Packages with Setuptools</a><ul>
<li><a class="reference internal" href="#developer-s-guide" id="id4">Developer’s Guide</a><ul>
<li><a class="reference internal" href="#installing-setuptools" id="id5">Installing <code class="docutils literal notranslate"><span class="pre">setuptools</span></code></a></li>
<li><a class="reference internal" href="#basic-use" id="id6">Basic Use</a><ul>
<li><a class="reference internal" href="#specifying-your-project-s-version" id="id7">Specifying Your Project’s Version</a></li>
</ul>
</li>
<li><a class="reference internal" href="#new-and-changed-setup-keywords" id="id8">New and Changed <code class="docutils literal notranslate"><span class="pre">setup()</span></code> Keywords</a><ul>
<li><a class="reference internal" href="#using-find-packages" id="id9">Using <code class="docutils literal notranslate"><span class="pre">find_packages()</span></code></a></li>
<li><a class="reference internal" href="#find-namespace-packages" id="id10"><code class="docutils literal notranslate"><span class="pre">find_namespace_packages()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#automatic-script-creation" id="id11">Automatic Script Creation</a><ul>
<li><a class="reference internal" href="#eggsecutable-scripts" id="id12">“Eggsecutable” Scripts</a></li>
</ul>
</li>
<li><a class="reference internal" href="#declaring-dependencies" id="id13">Declaring Dependencies</a><ul>
<li><a class="reference internal" href="#dependencies-that-aren-t-in-pypi" id="id14">Dependencies that aren’t in PyPI</a></li>
<li><a class="reference internal" href="#declaring-extras-optional-features-with-their-own-dependencies" id="id15">Declaring “Extras” (optional features with their own dependencies)</a></li>
<li><a class="reference internal" href="#declaring-platform-specific-dependencies" id="id16">Declaring platform specific dependencies</a></li>
</ul>
</li>
<li><a class="reference internal" href="#including-data-files" id="id17">Including Data Files</a><ul>
<li><a class="reference internal" href="#accessing-data-files-at-runtime" id="id18">Accessing Data Files at Runtime</a></li>
<li><a class="reference internal" href="#non-package-data-files" id="id19">Non-Package Data Files</a></li>
<li><a class="reference internal" href="#automatic-resource-extraction" id="id20">Automatic Resource Extraction</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extensible-applications-and-frameworks" id="id21">Extensible Applications and Frameworks</a><ul>
<li><a class="reference internal" href="#dynamic-discovery-of-services-and-plugins" id="id22">Dynamic Discovery of Services and Plugins</a></li>
<li><a class="reference internal" href="#defining-additional-metadata" id="id23">Defining Additional Metadata</a></li>
</ul>
</li>
<li><a class="reference internal" href="#development-mode" id="id24">“Development Mode”</a></li>
<li><a class="reference internal" href="#distributing-a-setuptools-based-project" id="id25">Distributing a <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>-based project</a><ul>
<li><a class="reference internal" href="#setting-the-zip-safe-flag" id="id26">Setting the <code class="docutils literal notranslate"><span class="pre">zip_safe</span></code> flag</a></li>
<li><a class="reference internal" href="#namespace-packages" id="id27">Namespace Packages</a><ul>
<li><a class="reference internal" href="#transitional-note" id="id28">TRANSITIONAL NOTE</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tagging-and-daily-build-or-snapshot-releases" id="id29">Tagging and “Daily Build” or “Snapshot” Releases</a></li>
<li><a class="reference internal" href="#generating-source-distributions" id="id30">Generating Source Distributions</a><ul>
<li><a class="reference internal" href="#making-official-non-snapshot-releases" id="id31">Making “Official” (Non-Snapshot) Releases</a></li>
</ul>
</li>
<li><a class="reference internal" href="#distributing-extensions-compiled-with-cython" id="id32">Distributing Extensions compiled with Cython</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#command-reference" id="id33">Command Reference</a><ul>
<li><a class="reference internal" href="#alias-define-shortcuts-for-commonly-used-commands" id="id34"><code class="docutils literal notranslate"><span class="pre">alias</span></code> - Define shortcuts for commonly used commands</a></li>
<li><a class="reference internal" href="#bdist-egg-create-a-python-egg-for-the-project" id="id35"><code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> - Create a Python Egg for the project</a></li>
<li><a class="reference internal" href="#develop-deploy-the-project-source-in-development-mode" id="id36"><code class="docutils literal notranslate"><span class="pre">develop</span></code> - Deploy the project source in “Development Mode”</a></li>
<li><a class="reference internal" href="#egg-info-create-egg-metadata-and-set-build-tags" id="id37"><code class="docutils literal notranslate"><span class="pre">egg_info</span></code> - Create egg metadata and set build tags</a><ul>
<li><a class="reference internal" href="#release-tagging-options" id="id38">Release Tagging Options</a></li>
<li><a class="reference internal" href="#other-egg-info-options" id="id39">Other <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> Options</a></li>
<li><a class="reference internal" href="#egg-info-examples" id="id40"><code class="docutils literal notranslate"><span class="pre">egg_info</span></code> Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#rotate-delete-outdated-distribution-files" id="id41"><code class="docutils literal notranslate"><span class="pre">rotate</span></code> - Delete outdated distribution files</a></li>
<li><a class="reference internal" href="#saveopts-save-used-options-to-a-configuration-file" id="id42"><code class="docutils literal notranslate"><span class="pre">saveopts</span></code> - Save used options to a configuration file</a><ul>
<li><a class="reference internal" href="#configuration-file-options" id="id43">Configuration File Options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#setopt-set-a-distutils-or-setuptools-option-in-a-config-file" id="id44"><code class="docutils literal notranslate"><span class="pre">setopt</span></code> - Set a distutils or setuptools option in a config file</a></li>
<li><a class="reference internal" href="#test-build-package-and-run-a-unittest-suite" id="id45"><code class="docutils literal notranslate"><span class="pre">test</span></code> - Build package and run a unittest suite</a></li>
<li><a class="reference internal" href="#upload-upload-source-and-or-egg-distributions-to-pypi" id="id46"><code class="docutils literal notranslate"><span class="pre">upload</span></code> - Upload source and/or egg distributions to PyPI</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-setup-using-setup-cfg-files" id="id47">Configuring setup() using setup.cfg files</a><ul>
<li><a class="reference internal" href="#using-a-src-layout" id="id48">Using a <code class="docutils literal notranslate"><span class="pre">src/</span></code> layout</a></li>
<li><a class="reference internal" href="#specifying-values" id="id49">Specifying values</a><ul>
<li><a class="reference internal" href="#metadata" id="id50">Metadata</a></li>
<li><a class="reference internal" href="#options" id="id51">Options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuration-api" id="id52">Configuration API</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extending-and-reusing-setuptools" id="id53">Extending and Reusing Setuptools</a><ul>
<li><a class="reference internal" href="#creating-distutils-extensions" id="id54">Creating <code class="docutils literal notranslate"><span class="pre">distutils</span></code> Extensions</a><ul>
<li><a class="reference internal" href="#adding-commands" id="id55">Adding Commands</a></li>
<li><a class="reference internal" href="#adding-setup-arguments" id="id56">Adding <code class="docutils literal notranslate"><span class="pre">setup()</span></code> Arguments</a></li>
<li><a class="reference internal" href="#customizing-distribution-options" id="id57">Customizing Distribution Options</a></li>
<li><a class="reference internal" href="#adding-new-egg-info-files" id="id58">Adding new EGG-INFO Files</a></li>
<li><a class="reference internal" href="#adding-support-for-revision-control-systems" id="id59">Adding Support for Revision Control Systems</a></li>
</ul>
</li>
<li><a class="reference internal" href="#mailing-list-and-bug-tracker" id="id60">Mailing List and Bug Tracker</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="developer-s-guide">
<h3><a class="toc-backref" href="#id4">Developer’s Guide</a><a class="headerlink" href="#developer-s-guide" title="Permalink to this headline">¶</a></h3>
<div class="section" id="installing-setuptools">
<h4><a class="toc-backref" href="#id5">Installing <code class="docutils literal notranslate"><span class="pre">setuptools</span></code></a><a class="headerlink" href="#installing-setuptools" title="Permalink to this headline">¶</a></h4>
<p>To install the latest version of setuptools, use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">setuptools</span>
</pre></div>
</div>
<p>Refer to <a class="reference external" href="https://packaging.python.org/tutorials/installing-packages/">Installing Packages</a> guide for more information.</p>
</div>
<div class="section" id="basic-use">
<h4><a class="toc-backref" href="#id6">Basic Use</a><a class="headerlink" href="#basic-use" title="Permalink to this headline">¶</a></h4>
<p>For basic use of setuptools, just import things from setuptools instead of
the distutils.  Here’s a minimal setup script using setuptools:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;HelloWorld&quot;</span><span class="p">,</span>
    <span class="n">version</span><span class="o">=</span><span class="s2">&quot;0.1&quot;</span><span class="p">,</span>
    <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">(),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>As you can see, it doesn’t take much to use setuptools in a project.
Run that script in your project folder, alongside the Python packages
you have developed.</p>
<p>Invoke that script to produce distributions and automatically include all
packages in the directory where the setup.py lives.  See the <a class="reference internal" href="#command-reference">Command
Reference</a> section below to see what commands you can give to this setup
script. For example, to produce a source distribution, simply invoke:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span>
</pre></div>
</div>
<p>Of course, before you release your project to PyPI, you’ll want to add a bit
more information to your setup script to help people find or learn about your
project.  And maybe your project will have grown by then to include a few
dependencies, and perhaps some data files and scripts:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;HelloWorld&quot;</span><span class="p">,</span>
    <span class="n">version</span><span class="o">=</span><span class="s2">&quot;0.1&quot;</span><span class="p">,</span>
    <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">(),</span>
    <span class="n">scripts</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;say_hello.py&quot;</span><span class="p">],</span>

    <span class="c1"># Project uses reStructuredText, so ensure that the docutils get</span>
    <span class="c1"># installed or upgraded on the target machine</span>
    <span class="n">install_requires</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;docutils&gt;=0.3&quot;</span><span class="p">],</span>

    <span class="n">package_data</span><span class="o">=</span><span class="p">{</span>
        <span class="c1"># If any package contains *.txt or *.rst files, include them:</span>
        <span class="s2">&quot;&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;*.txt&quot;</span><span class="p">,</span> <span class="s2">&quot;*.rst&quot;</span><span class="p">],</span>
        <span class="c1"># And include any *.msg files found in the &quot;hello&quot; package, too:</span>
        <span class="s2">&quot;hello&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;*.msg&quot;</span><span class="p">],</span>
    <span class="p">},</span>

    <span class="c1"># metadata to display on PyPI</span>
    <span class="n">author</span><span class="o">=</span><span class="s2">&quot;Me&quot;</span><span class="p">,</span>
    <span class="n">author_email</span><span class="o">=</span><span class="s2">&quot;me@example.com&quot;</span><span class="p">,</span>
    <span class="n">description</span><span class="o">=</span><span class="s2">&quot;This is an Example Package&quot;</span><span class="p">,</span>
    <span class="n">keywords</span><span class="o">=</span><span class="s2">&quot;hello world example examples&quot;</span><span class="p">,</span>
    <span class="n">url</span><span class="o">=</span><span class="s2">&quot;http://example.com/HelloWorld/&quot;</span><span class="p">,</span>   <span class="c1"># project home page, if any</span>
    <span class="n">project_urls</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;Bug Tracker&quot;</span><span class="p">:</span> <span class="s2">&quot;https://bugs.example.com/HelloWorld/&quot;</span><span class="p">,</span>
        <span class="s2">&quot;Documentation&quot;</span><span class="p">:</span> <span class="s2">&quot;https://docs.example.com/HelloWorld/&quot;</span><span class="p">,</span>
        <span class="s2">&quot;Source Code&quot;</span><span class="p">:</span> <span class="s2">&quot;https://code.example.com/HelloWorld/&quot;</span><span class="p">,</span>
    <span class="p">},</span>
    <span class="n">classifiers</span><span class="o">=</span><span class="p">[</span>
        <span class="s2">&quot;License :: OSI Approved :: Python Software Foundation License&quot;</span>
    <span class="p">]</span>

    <span class="c1"># could also include long_description, download_url, etc.</span>
<span class="p">)</span>
</pre></div>
</div>
<p>In the sections that follow, we’ll explain what most of these <code class="docutils literal notranslate"><span class="pre">setup()</span></code>
arguments do (except for the metadata ones), and the various ways you might use
them in your own project(s).</p>
<div class="section" id="specifying-your-project-s-version">
<h5><a class="toc-backref" href="#id7">Specifying Your Project’s Version</a><a class="headerlink" href="#specifying-your-project-s-version" title="Permalink to this headline">¶</a></h5>
<p>Setuptools can work well with most versioning schemes; there are, however, a
few special things to watch out for, in order to ensure that setuptools and
other tools can always tell what version of your package is newer than another
version.  Knowing these things will also help you correctly specify what
versions of other projects your project depends on.</p>
<p>A version consists of an alternating series of release numbers and pre-release
or post-release tags.  A release number is a series of digits punctuated by
dots, such as <code class="docutils literal notranslate"><span class="pre">2.4</span></code> or <code class="docutils literal notranslate"><span class="pre">0.5</span></code>.  Each series of digits is treated
numerically, so releases <code class="docutils literal notranslate"><span class="pre">2.1</span></code> and <code class="docutils literal notranslate"><span class="pre">2.1.0</span></code> are different ways to spell the
same release number, denoting the first subrelease of release 2.  But  <code class="docutils literal notranslate"><span class="pre">2.10</span></code>
is the <em>tenth</em> subrelease of release 2, and so is a different and newer release
from <code class="docutils literal notranslate"><span class="pre">2.1</span></code> or <code class="docutils literal notranslate"><span class="pre">2.1.0</span></code>.  Leading zeros within a series of digits are also
ignored, so <code class="docutils literal notranslate"><span class="pre">2.01</span></code> is the same as <code class="docutils literal notranslate"><span class="pre">2.1</span></code>, and different from <code class="docutils literal notranslate"><span class="pre">2.0.1</span></code>.</p>
<p>Following a release number, you can have either a pre-release or post-release
tag.  Pre-release tags make a version be considered <em>older</em> than the version
they are appended to.  So, revision <code class="docutils literal notranslate"><span class="pre">2.4</span></code> is <em>newer</em> than revision <code class="docutils literal notranslate"><span class="pre">2.4c1</span></code>,
which in turn is newer than <code class="docutils literal notranslate"><span class="pre">2.4b1</span></code> or <code class="docutils literal notranslate"><span class="pre">2.4a1</span></code>.  Postrelease tags make
a version be considered <em>newer</em> than the version they are appended to.  So,
revisions like <code class="docutils literal notranslate"><span class="pre">2.4-1</span></code> and <code class="docutils literal notranslate"><span class="pre">2.4pl3</span></code> are newer than <code class="docutils literal notranslate"><span class="pre">2.4</span></code>, but are <em>older</em>
than <code class="docutils literal notranslate"><span class="pre">2.4.1</span></code> (which has a higher release number).</p>
<p>A pre-release tag is a series of letters that are alphabetically before
“final”.  Some examples of prerelease tags would include <code class="docutils literal notranslate"><span class="pre">alpha</span></code>, <code class="docutils literal notranslate"><span class="pre">beta</span></code>,
<code class="docutils literal notranslate"><span class="pre">a</span></code>, <code class="docutils literal notranslate"><span class="pre">c</span></code>, <code class="docutils literal notranslate"><span class="pre">dev</span></code>, and so on.  You do not have to place a dot or dash
before the prerelease tag if it’s immediately after a number, but it’s okay to
do so if you prefer.  Thus, <code class="docutils literal notranslate"><span class="pre">2.4c1</span></code> and <code class="docutils literal notranslate"><span class="pre">2.4.c1</span></code> and <code class="docutils literal notranslate"><span class="pre">2.4-c1</span></code> all
represent release candidate 1 of version <code class="docutils literal notranslate"><span class="pre">2.4</span></code>, and are treated as identical
by setuptools.</p>
<p>In addition, there are three special prerelease tags that are treated as if
they were the letter <code class="docutils literal notranslate"><span class="pre">c</span></code>: <code class="docutils literal notranslate"><span class="pre">pre</span></code>, <code class="docutils literal notranslate"><span class="pre">preview</span></code>, and <code class="docutils literal notranslate"><span class="pre">rc</span></code>.  So, version
<code class="docutils literal notranslate"><span class="pre">2.4rc1</span></code>, <code class="docutils literal notranslate"><span class="pre">2.4pre1</span></code> and <code class="docutils literal notranslate"><span class="pre">2.4preview1</span></code> are all the exact same version as
<code class="docutils literal notranslate"><span class="pre">2.4c1</span></code>, and are treated as identical by setuptools.</p>
<p>A post-release tag is either a series of letters that are alphabetically
greater than or equal to “final”, or a dash (<code class="docutils literal notranslate"><span class="pre">-</span></code>).  Post-release tags are
generally used to separate patch numbers, port numbers, build numbers, revision
numbers, or date stamps from the release number.  For example, the version
<code class="docutils literal notranslate"><span class="pre">2.4-r1263</span></code> might denote Subversion revision 1263 of a post-release patch of
version <code class="docutils literal notranslate"><span class="pre">2.4</span></code>.  Or you might use <code class="docutils literal notranslate"><span class="pre">2.4-20051127</span></code> to denote a date-stamped
post-release.</p>
<p>Notice that after each pre or post-release tag, you are free to place another
release number, followed again by more pre- or post-release tags.  For example,
<code class="docutils literal notranslate"><span class="pre">0.6a9.dev-r41475</span></code> could denote Subversion revision 41475 of the in-
development version of the ninth alpha of release 0.6.  Notice that <code class="docutils literal notranslate"><span class="pre">dev</span></code> is
a pre-release tag, so this version is a <em>lower</em> version number than <code class="docutils literal notranslate"><span class="pre">0.6a9</span></code>,
which would be the actual ninth alpha of release 0.6.  But the <code class="docutils literal notranslate"><span class="pre">-r41475</span></code> is
a post-release tag, so this version is <em>newer</em> than <code class="docutils literal notranslate"><span class="pre">0.6a9.dev</span></code>.</p>
<p>For the most part, setuptools’ interpretation of version numbers is intuitive,
but here are a few tips that will keep you out of trouble in the corner cases:</p>
<ul>
<li><p class="first">Don’t stick adjoining pre-release tags together without a dot or number
between them.  Version <code class="docutils literal notranslate"><span class="pre">1.9adev</span></code> is the <code class="docutils literal notranslate"><span class="pre">adev</span></code> prerelease of <code class="docutils literal notranslate"><span class="pre">1.9</span></code>,
<em>not</em> a development pre-release of <code class="docutils literal notranslate"><span class="pre">1.9a</span></code>.  Use <code class="docutils literal notranslate"><span class="pre">.dev</span></code> instead, as in
<code class="docutils literal notranslate"><span class="pre">1.9a.dev</span></code>, or separate the prerelease tags with a number, as in
<code class="docutils literal notranslate"><span class="pre">1.9a0dev</span></code>.  <code class="docutils literal notranslate"><span class="pre">1.9a.dev</span></code>, <code class="docutils literal notranslate"><span class="pre">1.9a0dev</span></code>, and even <code class="docutils literal notranslate"><span class="pre">1.9.a.dev</span></code> are
identical versions from setuptools’ point of view, so you can use whatever
scheme you prefer.</p>
</li>
<li><p class="first">If you want to be certain that your chosen numbering scheme works the way
you think it will, you can use the <code class="docutils literal notranslate"><span class="pre">pkg_resources.parse_version()</span></code> function
to compare different version numbers:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">pkg_resources</span> <span class="k">import</span> <span class="n">parse_version</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parse_version</span><span class="p">(</span><span class="s2">&quot;1.9.a.dev&quot;</span><span class="p">)</span> <span class="o">==</span> <span class="n">parse_version</span><span class="p">(</span><span class="s2">&quot;1.9a0dev&quot;</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parse_version</span><span class="p">(</span><span class="s2">&quot;2.1-rc2&quot;</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">parse_version</span><span class="p">(</span><span class="s2">&quot;2.1&quot;</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parse_version</span><span class="p">(</span><span class="s2">&quot;0.6a9dev-r41475&quot;</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">parse_version</span><span class="p">(</span><span class="s2">&quot;0.6a9&quot;</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
</li>
</ul>
<p>Once you’ve decided on a version numbering scheme for your project, you can
have setuptools automatically tag your in-development releases with various
pre- or post-release tags.  See the following sections for more details:</p>
<ul class="simple">
<li><a class="reference internal" href="#tagging-and-daily-build-or-snapshot-releases">Tagging and “Daily Build” or “Snapshot” Releases</a></li>
<li>The <a class="reference internal" href="#egg-info">egg_info</a> command</li>
</ul>
</div>
</div>
<div class="section" id="new-and-changed-setup-keywords">
<h4><a class="toc-backref" href="#id8">New and Changed <code class="docutils literal notranslate"><span class="pre">setup()</span></code> Keywords</a><a class="headerlink" href="#new-and-changed-setup-keywords" title="Permalink to this headline">¶</a></h4>
<p>The following keyword arguments to <code class="docutils literal notranslate"><span class="pre">setup()</span></code> are added or changed by
<code class="docutils literal notranslate"><span class="pre">setuptools</span></code>.  All of them are optional; you do not have to supply them
unless you need the associated <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> feature.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">include_package_data</span></code></dt>
<dd>If set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, this tells <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> to automatically include any
data files it finds inside your package directories that are specified by
your <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> file.  For more information, see the section below on
<a class="reference internal" href="#including-data-files">Including Data Files</a>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">exclude_package_data</span></code></dt>
<dd>A dictionary mapping package names to lists of glob patterns that should
be <em>excluded</em> from your package directories.  You can use this to trim back
any excess files included by <code class="docutils literal notranslate"><span class="pre">include_package_data</span></code>.  For a complete
description and examples, see the section below on <a class="reference internal" href="#including-data-files">Including Data Files</a>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">package_data</span></code></dt>
<dd>A dictionary mapping package names to lists of glob patterns.  For a
complete description and examples, see the section below on <a class="reference internal" href="#including-data-files">Including
Data Files</a>.  You do not need to use this option if you are using
<code class="docutils literal notranslate"><span class="pre">include_package_data</span></code>, unless you need to add e.g. files that are
generated by your setup script and build process.  (And are therefore not
in source control or are files that you don’t want to include in your
source distribution.)</dd>
<dt><code class="docutils literal notranslate"><span class="pre">zip_safe</span></code></dt>
<dd>A boolean (True or False) flag specifying whether the project can be
safely installed and run from a zip file.  If this argument is not
supplied, the <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> command will have to analyze all of your
project’s contents for possible problems each time it builds an egg.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">install_requires</span></code></dt>
<dd>A string or list of strings specifying what other distributions need to
be installed when this one is.  See the section below on <a class="reference internal" href="#declaring-dependencies">Declaring
Dependencies</a> for details and examples of the format of this argument.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">entry_points</span></code></dt>
<dd>A dictionary mapping entry point group names to strings or lists of strings
defining the entry points.  Entry points are used to support dynamic
discovery of services or plugins provided by a project.  See <a class="reference internal" href="#dynamic-discovery-of-services-and-plugins">Dynamic
Discovery of Services and Plugins</a> for details and examples of the format
of this argument.  In addition, this keyword is used to support <a class="reference internal" href="#automatic-script-creation">Automatic
Script Creation</a>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">extras_require</span></code></dt>
<dd>A dictionary mapping names of “extras” (optional features of your project)
to strings or lists of strings specifying what other distributions must be
installed to support those features.  See the section below on <a class="reference internal" href="#declaring-dependencies">Declaring
Dependencies</a> for details and examples of the format of this argument.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">python_requires</span></code></dt>
<dd>A string corresponding to a version specifier (as defined in PEP 440) for
the Python version, used to specify the Requires-Python defined in PEP 345.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">setup_requires</span></code></dt>
<dd><p class="first">A string or list of strings specifying what other distributions need to
be present in order for the <em>setup script</em> to run.  <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> will
attempt to obtain these (using pip if available) before processing the
rest of the setup script or commands.  This argument is needed if you
are using distutils extensions as part of your build process; for
example, extensions that process setup() arguments and turn them into
EGG-INFO metadata files.</p>
<p class="last">(Note: projects listed in <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> will NOT be automatically
installed on the system where the setup script is being run.  They are
simply downloaded to the ./.eggs directory if they’re not locally available
already.  If you want them to be installed, as well as being available
when the setup script is run, you should add them to <code class="docutils literal notranslate"><span class="pre">install_requires</span></code>
<strong>and</strong> <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code>.)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">dependency_links</span></code></dt>
<dd>A list of strings naming URLs to be searched when satisfying dependencies.
These links will be used if needed to install packages specified by
<code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> or <code class="docutils literal notranslate"><span class="pre">tests_require</span></code>.  They will also be written into
the egg’s metadata for use during install by tools that support them.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">namespace_packages</span></code></dt>
<dd>A list of strings naming the project’s “namespace packages”.  A namespace
package is a package that may be split across multiple project
distributions.  For example, Zope 3’s <code class="docutils literal notranslate"><span class="pre">zope</span></code> package is a namespace
package, because subpackages like <code class="docutils literal notranslate"><span class="pre">zope.interface</span></code> and <code class="docutils literal notranslate"><span class="pre">zope.publisher</span></code>
may be distributed separately.  The egg runtime system can automatically
merge such subpackages into a single parent package at runtime, as long
as you declare them in each project that contains any subpackages of the
namespace package, and as long as the namespace package’s <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>
does not contain any code other than a namespace declaration.  See the
section below on <a class="reference internal" href="#namespace-packages">Namespace Packages</a> for more information.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">test_suite</span></code></dt>
<dd><p class="first">A string naming a <code class="docutils literal notranslate"><span class="pre">unittest.TestCase</span></code> subclass (or a package or module
containing one or more of them, or a method of such a subclass), or naming
a function that can be called with no arguments and returns a
<code class="docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code>.  If the named suite is a module, and the module
has an <code class="docutils literal notranslate"><span class="pre">additional_tests()</span></code> function, it is called and the results are
added to the tests to be run.  If the named suite is a package, any
submodules and subpackages are recursively added to the overall test suite.</p>
<p>Specifying this argument enables use of the <a class="reference internal" href="#test">test</a> command to run the
specified test suite, e.g. via <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">test</span></code>.  See the section on the
<a class="reference internal" href="#test">test</a> command below for more details.</p>
<p class="last">New in 41.5.0: Deprecated the test command.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">tests_require</span></code></dt>
<dd><p class="first">If your project’s tests need one or more additional packages besides those
needed to install it, you can use this option to specify them.  It should
be a string or list of strings specifying what other distributions need to
be present for the package’s tests to run.  When you run the <code class="docutils literal notranslate"><span class="pre">test</span></code>
command, <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> will  attempt to obtain these (using pip if
available).  Note that these required projects will <em>not</em> be installed on
the system where the tests are run, but only downloaded to the project’s setup
directory if they’re not already installed locally.</p>
<p class="last">New in 41.5.0: Deprecated the test command.</p>
</dd>
</dl>
<dl class="docutils" id="test-loader">
<dt><code class="docutils literal notranslate"><span class="pre">test_loader</span></code></dt>
<dd><p class="first">If you would like to use a different way of finding tests to run than what
setuptools normally uses, you can specify a module name and class name in
this argument.  The named class must be instantiable with no arguments, and
its instances must support the <code class="docutils literal notranslate"><span class="pre">loadTestsFromNames()</span></code> method as defined
in the Python <code class="docutils literal notranslate"><span class="pre">unittest</span></code> module’s <code class="docutils literal notranslate"><span class="pre">TestLoader</span></code> class.  Setuptools will
pass only one test “name” in the <cite>names</cite> argument: the value supplied for
the <code class="docutils literal notranslate"><span class="pre">test_suite</span></code> argument.  The loader you specify may interpret this
string in any way it likes, as there are no restrictions on what may be
contained in a <code class="docutils literal notranslate"><span class="pre">test_suite</span></code> string.</p>
<p>The module name and class name must be separated by a <code class="docutils literal notranslate"><span class="pre">:</span></code>.  The default
value of this argument is <code class="docutils literal notranslate"><span class="pre">&quot;setuptools.command.test:ScanningLoader&quot;</span></code>.  If
you want to use the default <code class="docutils literal notranslate"><span class="pre">unittest</span></code> behavior, you can specify
<code class="docutils literal notranslate"><span class="pre">&quot;unittest:TestLoader&quot;</span></code> as your <code class="docutils literal notranslate"><span class="pre">test_loader</span></code> argument instead.  This
will prevent automatic scanning of submodules and subpackages.</p>
<p>The module and class you specify here may be contained in another package,
as long as you use the <code class="docutils literal notranslate"><span class="pre">tests_require</span></code> option to ensure that the package
containing the loader class is available when the <code class="docutils literal notranslate"><span class="pre">test</span></code> command is run.</p>
<p class="last">New in 41.5.0: Deprecated the test command.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">eager_resources</span></code></dt>
<dd><p class="first">A list of strings naming resources that should be extracted together, if
any of them is needed, or if any C extensions included in the project are
imported.  This argument is only useful if the project will be installed as
a zipfile, and there is a need to have all of the listed resources be
extracted to the filesystem <em>as a unit</em>.  Resources listed here
should be “/”-separated paths, relative to the source root, so to list a
resource <code class="docutils literal notranslate"><span class="pre">foo.png</span></code> in package <code class="docutils literal notranslate"><span class="pre">bar.baz</span></code>, you would include the string
<code class="docutils literal notranslate"><span class="pre">bar/baz/foo.png</span></code> in this argument.</p>
<p class="last">If you only need to obtain resources one at a time, or you don’t have any C
extensions that access other files in the project (such as data files or
shared libraries), you probably do NOT need this argument and shouldn’t
mess with it.  For more details on how this argument works, see the section
below on <a class="reference internal" href="#automatic-resource-extraction">Automatic Resource Extraction</a>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">use_2to3</span></code></dt>
<dd>Convert the source code from Python 2 to Python 3 with 2to3 during the
build process. See <a class="reference internal" href="index.html#document-python3"><span class="doc">Supporting both Python 2 and Python 3 with Setuptools</span></a> for more details.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">convert_2to3_doctests</span></code></dt>
<dd>List of doctest source files that need to be converted with 2to3.
See <a class="reference internal" href="index.html#document-python3"><span class="doc">Supporting both Python 2 and Python 3 with Setuptools</span></a> for more details.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">use_2to3_fixers</span></code></dt>
<dd>A list of modules to search for additional fixers to be used during
the 2to3 conversion. See <a class="reference internal" href="index.html#document-python3"><span class="doc">Supporting both Python 2 and Python 3 with Setuptools</span></a> for more details.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">project_urls</span></code></dt>
<dd>An arbitrary map of URL names to hyperlinks, allowing more extensible
documentation of where various resources can be found than the simple
<code class="docutils literal notranslate"><span class="pre">url</span></code> and <code class="docutils literal notranslate"><span class="pre">download_url</span></code> options provide.</dd>
</dl>
<div class="section" id="using-find-packages">
<h5><a class="toc-backref" href="#id9">Using <code class="docutils literal notranslate"><span class="pre">find_packages()</span></code></a><a class="headerlink" href="#using-find-packages" title="Permalink to this headline">¶</a></h5>
<p>For simple projects, it’s usually easy enough to manually add packages to
the <code class="docutils literal notranslate"><span class="pre">packages</span></code> argument of <code class="docutils literal notranslate"><span class="pre">setup()</span></code>.  However, for very large projects
(Twisted, PEAK, Zope, Chandler, etc.), it can be a big burden to keep the
package list updated.  That’s what <code class="docutils literal notranslate"><span class="pre">setuptools.find_packages()</span></code> is for.</p>
<p><code class="docutils literal notranslate"><span class="pre">find_packages()</span></code> takes a source directory and two lists of package name
patterns to exclude and include.  If omitted, the source directory defaults to
the same
directory as the setup script.  Some projects use a <code class="docutils literal notranslate"><span class="pre">src</span></code> or <code class="docutils literal notranslate"><span class="pre">lib</span></code>
directory as the root of their source tree, and those projects would of course
use <code class="docutils literal notranslate"><span class="pre">&quot;src&quot;</span></code> or <code class="docutils literal notranslate"><span class="pre">&quot;lib&quot;</span></code> as the first argument to <code class="docutils literal notranslate"><span class="pre">find_packages()</span></code>.  (And
such projects also need something like <code class="docutils literal notranslate"><span class="pre">package_dir={&quot;&quot;:</span> <span class="pre">&quot;src&quot;}</span></code> in their
<code class="docutils literal notranslate"><span class="pre">setup()</span></code> arguments, but that’s just a normal distutils thing.)</p>
<p>Anyway, <code class="docutils literal notranslate"><span class="pre">find_packages()</span></code> walks the target directory, filtering by inclusion
patterns, and finds Python packages (any directory). Packages are only
recognized if they include an <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file. Finally, exclusion
patterns are applied to remove matching packages.</p>
<p>Inclusion and exclusion patterns are package names, optionally including
wildcards.  For
example, <code class="docutils literal notranslate"><span class="pre">find_packages(exclude=[&quot;*.tests&quot;])</span></code> will exclude all packages whose
last name part is <code class="docutils literal notranslate"><span class="pre">tests</span></code>.   Or, <code class="docutils literal notranslate"><span class="pre">find_packages(exclude=[&quot;*.tests&quot;,</span>
<span class="pre">&quot;*.tests.*&quot;])</span></code> will also exclude any subpackages of packages named <code class="docutils literal notranslate"><span class="pre">tests</span></code>,
but it still won’t exclude a top-level <code class="docutils literal notranslate"><span class="pre">tests</span></code> package or the children
thereof.  In fact, if you really want no <code class="docutils literal notranslate"><span class="pre">tests</span></code> packages at all, you’ll need
something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">find_packages</span><span class="p">(</span><span class="n">exclude</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;*.tests&quot;</span><span class="p">,</span> <span class="s2">&quot;*.tests.*&quot;</span><span class="p">,</span> <span class="s2">&quot;tests.*&quot;</span><span class="p">,</span> <span class="s2">&quot;tests&quot;</span><span class="p">])</span>
</pre></div>
</div>
<p>in order to cover all the bases.  Really, the exclusion patterns are intended
to cover simpler use cases than this, like excluding a single, specified
package and its subpackages.</p>
<p>Regardless of the parameters, the <code class="docutils literal notranslate"><span class="pre">find_packages()</span></code>
function returns a list of package names suitable for use as the <code class="docutils literal notranslate"><span class="pre">packages</span></code>
argument to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>, and so is usually the easiest way to set that
argument in your setup script.  Especially since it frees you from having to
remember to modify your setup script whenever your project grows additional
top-level packages or subpackages.</p>
</div>
<div class="section" id="find-namespace-packages">
<h5><a class="toc-backref" href="#id10"><code class="docutils literal notranslate"><span class="pre">find_namespace_packages()</span></code></a><a class="headerlink" href="#find-namespace-packages" title="Permalink to this headline">¶</a></h5>
<p>In Python 3.3+, <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> also provides the <code class="docutils literal notranslate"><span class="pre">find_namespace_packages</span></code> variant
of <code class="docutils literal notranslate"><span class="pre">find_packages</span></code>, which has the same function signature as
<code class="docutils literal notranslate"><span class="pre">find_packages</span></code>, but works with <a class="reference external" href="https://www.python.org/dev/peps/pep-0420/">PEP 420</a> compliant implicit namespace
packages. Here is a minimal setup script using <code class="docutils literal notranslate"><span class="pre">find_namespace_packages</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_namespace_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;HelloWorld&quot;</span><span class="p">,</span>
    <span class="n">version</span><span class="o">=</span><span class="s2">&quot;0.1&quot;</span><span class="p">,</span>
    <span class="n">packages</span><span class="o">=</span><span class="n">find_namespace_packages</span><span class="p">(),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Keep in mind that according to PEP 420, you may have to either re-organize your
codebase a bit or define a few exclusions, as the definition of an implicit
namespace package is quite lenient, so for a project organized like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>├── namespace
│   └── mypackage
│       ├── __init__.py
│       └── mod1.py
├── setup.py
└── tests
    └── test_mod1.py
</pre></div>
</div>
<p>A naive <code class="docutils literal notranslate"><span class="pre">find_namespace_packages()</span></code> would install both <code class="docutils literal notranslate"><span class="pre">namespace.mypackage</span></code> and a
top-level package called <code class="docutils literal notranslate"><span class="pre">tests</span></code>! One way to avoid this problem is to use the
<code class="docutils literal notranslate"><span class="pre">include</span></code> keyword to whitelist the packages to include, like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_namespace_packages</span>

<span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;namespace.mypackage&quot;</span><span class="p">,</span>
    <span class="n">version</span><span class="o">=</span><span class="s2">&quot;0.1&quot;</span><span class="p">,</span>
    <span class="n">packages</span><span class="o">=</span><span class="n">find_namespace_packages</span><span class="p">(</span><span class="n">include</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;namespace.*&quot;</span><span class="p">])</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Another option is to use the “src” layout, where all package code is placed in
the <code class="docutils literal notranslate"><span class="pre">src</span></code> directory, like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>├── setup.py
├── src
│   └── namespace
│       └── mypackage
│           ├── __init__.py
│           └── mod1.py
└── tests
    └── test_mod1.py
</pre></div>
</div>
<p>With this layout, the package directory is specified as <code class="docutils literal notranslate"><span class="pre">src</span></code>, as such:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;namespace.mypackage&quot;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s2">&quot;0.1&quot;</span><span class="p">,</span>
      <span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;&quot;</span><span class="p">:</span> <span class="s2">&quot;src&quot;</span><span class="p">},</span>
      <span class="n">packages</span><span class="o">=</span><span class="n">find_namespace_packages</span><span class="p">(</span><span class="n">where</span><span class="o">=</span><span class="s2">&quot;src&quot;</span><span class="p">))</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="automatic-script-creation">
<h4><a class="toc-backref" href="#id11">Automatic Script Creation</a><a class="headerlink" href="#automatic-script-creation" title="Permalink to this headline">¶</a></h4>
<p>Packaging and installing scripts can be a bit awkward with the distutils.  For
one thing, there’s no easy way to have a script’s filename match local
conventions on both Windows and POSIX platforms.  For another, you often have
to create a separate file just for the “main” script, when your actual “main”
is a function in a module somewhere.  And even in Python 2.4, using the <code class="docutils literal notranslate"><span class="pre">-m</span></code>
option only works for actual <code class="docutils literal notranslate"><span class="pre">.py</span></code> files that aren’t installed in a package.</p>
<p><code class="docutils literal notranslate"><span class="pre">setuptools</span></code> fixes all of these problems by automatically generating scripts
for you with the correct extension, and on Windows it will even create an
<code class="docutils literal notranslate"><span class="pre">.exe</span></code> file so that users don’t have to change their <code class="docutils literal notranslate"><span class="pre">PATHEXT</span></code> settings.
The way to use this feature is to define “entry points” in your setup script
that indicate what function the generated script should import and run.  For
example, to create two console scripts called <code class="docutils literal notranslate"><span class="pre">foo</span></code> and <code class="docutils literal notranslate"><span class="pre">bar</span></code>, and a GUI
script called <code class="docutils literal notranslate"><span class="pre">baz</span></code>, you might do something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># other arguments here...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;console_scripts&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;foo = my_package.some_module:main_func&quot;</span><span class="p">,</span>
            <span class="s2">&quot;bar = other_module:some_func&quot;</span><span class="p">,</span>
        <span class="p">],</span>
        <span class="s2">&quot;gui_scripts&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;baz = my_package_gui:start_func&quot;</span><span class="p">,</span>
        <span class="p">]</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>When this project is installed on non-Windows platforms (using “setup.py
install”, “setup.py develop”, or with pip), a set of <code class="docutils literal notranslate"><span class="pre">foo</span></code>, <code class="docutils literal notranslate"><span class="pre">bar</span></code>,
and <code class="docutils literal notranslate"><span class="pre">baz</span></code> scripts will be installed that import <code class="docutils literal notranslate"><span class="pre">main_func</span></code> and
<code class="docutils literal notranslate"><span class="pre">some_func</span></code> from the specified modules.  The functions you specify are
called with no arguments, and their return value is passed to
<code class="docutils literal notranslate"><span class="pre">sys.exit()</span></code>, so you can return an errorlevel or message to print to
stderr.</p>
<p>On Windows, a set of <code class="docutils literal notranslate"><span class="pre">foo.exe</span></code>, <code class="docutils literal notranslate"><span class="pre">bar.exe</span></code>, and <code class="docutils literal notranslate"><span class="pre">baz.exe</span></code> launchers are
created, alongside a set of <code class="docutils literal notranslate"><span class="pre">foo.py</span></code>, <code class="docutils literal notranslate"><span class="pre">bar.py</span></code>, and <code class="docutils literal notranslate"><span class="pre">baz.pyw</span></code> files.  The
<code class="docutils literal notranslate"><span class="pre">.exe</span></code> wrappers find and execute the right version of Python to run the
<code class="docutils literal notranslate"><span class="pre">.py</span></code> or <code class="docutils literal notranslate"><span class="pre">.pyw</span></code> file.</p>
<p>You may define as many “console script” and “gui script” entry points as you
like, and each one can optionally specify “extras” that it depends on, that
will be added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> when the script is run.  For more information on
“extras”, see the section below on <a class="reference internal" href="#declaring-extras">Declaring Extras</a>.  For more information
on “entry points” in general, see the section below on <a class="reference internal" href="#dynamic-discovery-of-services-and-plugins">Dynamic Discovery of
Services and Plugins</a>.</p>
<div class="section" id="eggsecutable-scripts">
<h5><a class="toc-backref" href="#id12">“Eggsecutable” Scripts</a><a class="headerlink" href="#eggsecutable-scripts" title="Permalink to this headline">¶</a></h5>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 45.3.0.</span></p>
</div>
<p>Occasionally, there are situations where it’s desirable to make an <code class="docutils literal notranslate"><span class="pre">.egg</span></code>
file directly executable.  You can do this by including an entry point such
as the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># other arguments here...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;setuptools.installation&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;eggsecutable = my_package.some_module:main_func&quot;</span><span class="p">,</span>
        <span class="p">]</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Any eggs built from the above setup script will include a short executable
prelude that imports and calls <code class="docutils literal notranslate"><span class="pre">main_func()</span></code> from <code class="docutils literal notranslate"><span class="pre">my_package.some_module</span></code>.
The prelude can be run on Unix-like platforms (including Mac and Linux) by
invoking the egg with <code class="docutils literal notranslate"><span class="pre">/bin/sh</span></code>, or by enabling execute permissions on the
<code class="docutils literal notranslate"><span class="pre">.egg</span></code> file.  For the executable prelude to run, the appropriate version of
Python must be available via the <code class="docutils literal notranslate"><span class="pre">PATH</span></code> environment variable, under its
“long” name.  That is, if the egg is built for Python 2.3, there must be a
<code class="docutils literal notranslate"><span class="pre">python2.3</span></code> executable present in a directory on <code class="docutils literal notranslate"><span class="pre">PATH</span></code>.</p>
<p>IMPORTANT NOTE: Eggs with an “eggsecutable” header cannot be renamed, or
invoked via symlinks.  They <em>must</em> be invoked using their original filename, in
order to ensure that, once running, <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> will know what project
and version is in use.  The header script will check this and exit with an
error if the <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file has been renamed or is invoked via a symlink that
changes its base name.</p>
</div>
</div>
<div class="section" id="declaring-dependencies">
<h4><a class="toc-backref" href="#id13">Declaring Dependencies</a><a class="headerlink" href="#declaring-dependencies" title="Permalink to this headline">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">setuptools</span></code> supports automatically installing dependencies when a package is
installed, and including information about dependencies in Python Eggs (so that
package management tools like pip can use the information).</p>
<p><code class="docutils literal notranslate"><span class="pre">setuptools</span></code> and <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> use a common syntax for specifying a
project’s required dependencies.  This syntax consists of a project’s PyPI
name, optionally followed by a comma-separated list of “extras” in square
brackets, optionally followed by a comma-separated list of version
specifiers.  A version specifier is one of the operators <code class="docutils literal notranslate"><span class="pre">&lt;</span></code>, <code class="docutils literal notranslate"><span class="pre">&gt;</span></code>, <code class="docutils literal notranslate"><span class="pre">&lt;=</span></code>,
<code class="docutils literal notranslate"><span class="pre">&gt;=</span></code>, <code class="docutils literal notranslate"><span class="pre">==</span></code> or <code class="docutils literal notranslate"><span class="pre">!=</span></code>, followed by a version identifier.  Tokens may be
separated by whitespace, but any whitespace or nonstandard characters within a
project name or version identifier must be replaced with <code class="docutils literal notranslate"><span class="pre">-</span></code>.</p>
<p>Version specifiers for a given project are internally sorted into ascending
version order, and used to establish what ranges of versions are acceptable.
Adjacent redundant conditions are also consolidated (e.g. <code class="docutils literal notranslate"><span class="pre">&quot;&gt;1,</span> <span class="pre">&gt;2&quot;</span></code> becomes
<code class="docutils literal notranslate"><span class="pre">&quot;&gt;2&quot;</span></code>, and <code class="docutils literal notranslate"><span class="pre">&quot;&lt;2,&lt;3&quot;</span></code> becomes <code class="docutils literal notranslate"><span class="pre">&quot;&lt;2&quot;</span></code>). <code class="docutils literal notranslate"><span class="pre">&quot;!=&quot;</span></code> versions are excised from
the ranges they fall within.  A project’s version is then checked for
membership in the resulting ranges. (Note that providing conflicting conditions
for the same version (e.g. “&lt;2,&gt;=2” or “==2,!=2”) is meaningless and may
therefore produce bizarre results.)</p>
<p>Here are some example requirement specifiers:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">docutils</span> <span class="o">&gt;=</span> <span class="mf">0.3</span>

<span class="c1"># comment lines and \ continuations are allowed in requirement strings</span>
<span class="n">BazSpam</span> <span class="o">==</span><span class="mf">1.1</span><span class="p">,</span> <span class="o">==</span><span class="mf">1.2</span><span class="p">,</span> <span class="o">==</span><span class="mf">1.3</span><span class="p">,</span> <span class="o">==</span><span class="mf">1.4</span><span class="p">,</span> <span class="o">==</span><span class="mf">1.5</span><span class="p">,</span> \
    <span class="o">==</span><span class="mf">1.6</span><span class="p">,</span> <span class="o">==</span><span class="mf">1.7</span>  <span class="c1"># and so are line-end comments</span>

<span class="n">PEAK</span><span class="p">[</span><span class="n">FastCGI</span><span class="p">,</span> <span class="n">reST</span><span class="p">]</span><span class="o">&gt;=</span><span class="mf">0.5</span><span class="n">a4</span>

<span class="n">setuptools</span><span class="o">==</span><span class="mf">0.5</span><span class="n">a7</span>
</pre></div>
</div>
<p>The simplest way to include requirement specifiers is to use the
<code class="docutils literal notranslate"><span class="pre">install_requires</span></code> argument to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>.  It takes a string or list of
strings containing requirement specifiers.  If you include more than one
requirement in a string, each requirement must begin on a new line.</p>
<p>This has three effects:</p>
<ol class="arabic simple">
<li>When your project is installed, either by using pip, <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">install</span></code>,
or <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code>, all of the dependencies not already installed will
be located (via PyPI), downloaded, built (if necessary), and installed.</li>
<li>Any scripts in your project will be installed with wrappers that verify
the availability of the specified dependencies at runtime, and ensure that
the correct versions are added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> (e.g. if multiple versions
have been installed).</li>
<li>Python Egg distributions will include a metadata file listing the
dependencies.</li>
</ol>
<p>Note, by the way, that if you declare your dependencies in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>, you do
<em>not</em> need to use the <code class="docutils literal notranslate"><span class="pre">require()</span></code> function in your scripts or modules, as
long as you either install the project or use <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code> to do
development work on it.  (See <a class="reference internal" href="#development-mode">“Development Mode”</a> below for more details on
using <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code>.)</p>
<div class="section" id="dependencies-that-aren-t-in-pypi">
<h5><a class="toc-backref" href="#id14">Dependencies that aren’t in PyPI</a><a class="headerlink" href="#dependencies-that-aren-t-in-pypi" title="Permalink to this headline">¶</a></h5>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Dependency links support has been dropped by pip starting with version
19.0 (released 2019-01-22).</p>
</div>
<p>If your project depends on packages that don’t exist on PyPI, you may still be
able to depend on them, as long as they are available for download as:</p>
<ul class="simple">
<li>an egg, in the standard distutils <code class="docutils literal notranslate"><span class="pre">sdist</span></code> format,</li>
<li>a single <code class="docutils literal notranslate"><span class="pre">.py</span></code> file, or</li>
<li>a VCS repository (Subversion, Mercurial, or Git).</li>
</ul>
<p>You just need to add some URLs to the <code class="docutils literal notranslate"><span class="pre">dependency_links</span></code> argument to
<code class="docutils literal notranslate"><span class="pre">setup()</span></code>.</p>
<p>The URLs must be either:</p>
<ol class="arabic simple">
<li>direct download URLs,</li>
<li>the URLs of web pages that contain direct download links, or</li>
<li>the repository’s URL</li>
</ol>
<p>In general, it’s better to link to web pages, because it is usually less
complex to update a web page than to release a new version of your project.
You can also use a SourceForge <code class="docutils literal notranslate"><span class="pre">showfiles.php</span></code> link in the case where a
package you depend on is distributed via SourceForge.</p>
<p>If you depend on a package that’s distributed as a single <code class="docutils literal notranslate"><span class="pre">.py</span></code> file, you
must include an <code class="docutils literal notranslate"><span class="pre">&quot;#egg=project-version&quot;</span></code> suffix to the URL, to give a project
name and version number.  (Be sure to escape any dashes in the name or version
by replacing them with underscores.)  EasyInstall will recognize this suffix
and automatically create a trivial <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> to wrap the single <code class="docutils literal notranslate"><span class="pre">.py</span></code> file
as an egg.</p>
<p>In the case of a VCS checkout, you should also append <code class="docutils literal notranslate"><span class="pre">#egg=project-version</span></code>
in order to identify for what package that checkout should be used. You can
append <code class="docutils literal notranslate"><span class="pre">&#64;REV</span></code> to the URL’s path (before the fragment) to specify a revision.
Additionally, you can also force the VCS being used by prepending the URL with
a certain prefix. Currently available are:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">svn+URL</span></code> for Subversion,</li>
<li><code class="docutils literal notranslate"><span class="pre">git+URL</span></code> for Git, and</li>
<li><code class="docutils literal notranslate"><span class="pre">hg+URL</span></code> for Mercurial</li>
</ul>
<p>A more complete example would be:</p>
<blockquote>
<div><code class="docutils literal notranslate"><span class="pre">vcs+proto://host/path&#64;revision#egg=project-version</span></code></div></blockquote>
<p>Be careful with the version. It should match the one inside the project files.
If you want to disregard the version, you have to omit it both in the
<code class="docutils literal notranslate"><span class="pre">requires</span></code> and in the URL’s fragment.</p>
<p>This will do a checkout (or a clone, in Git and Mercurial parlance) to a
temporary folder and run <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">bdist_egg</span></code>.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">dependency_links</span></code> option takes the form of a list of URL strings.  For
example, this will cause a search of the specified page for eggs or source
distributions, if the package’s dependencies aren’t already installed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">dependency_links</span><span class="o">=</span><span class="p">[</span>
        <span class="s2">&quot;http://peak.telecommunity.com/snapshots/&quot;</span>
    <span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="declaring-extras-optional-features-with-their-own-dependencies">
<span id="declaring-extras"></span><h5><a class="toc-backref" href="#id15">Declaring “Extras” (optional features with their own dependencies)</a><a class="headerlink" href="#declaring-extras-optional-features-with-their-own-dependencies" title="Permalink to this headline">¶</a></h5>
<p>Sometimes a project has “recommended” dependencies, that are not required for
all uses of the project.  For example, a project might offer optional PDF
output if ReportLab is installed, and reStructuredText support if docutils is
installed.  These optional features are called “extras”, and setuptools allows
you to define their requirements as well.  In this way, other projects that
require these optional features can force the additional requirements to be
installed, by naming the desired extras in their <code class="docutils literal notranslate"><span class="pre">install_requires</span></code>.</p>
<p>For example, let’s say that Project A offers optional PDF and reST support:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Project-A&quot;</span><span class="p">,</span>
    <span class="o">...</span>
    <span class="n">extras_require</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;PDF&quot;</span><span class="p">:</span>  <span class="p">[</span><span class="s2">&quot;ReportLab&gt;=1.2&quot;</span><span class="p">,</span> <span class="s2">&quot;RXP&quot;</span><span class="p">],</span>
        <span class="s2">&quot;reST&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;docutils&gt;=0.3&quot;</span><span class="p">],</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>As you can see, the <code class="docutils literal notranslate"><span class="pre">extras_require</span></code> argument takes a dictionary mapping
names of “extra” features, to strings or lists of strings describing those
features’ requirements.  These requirements will <em>not</em> be automatically
installed unless another package depends on them (directly or indirectly) by
including the desired “extras” in square brackets after the associated project
name.  (Or if the extras were listed in a requirement spec on the “pip install”
command line.)</p>
<p>Extras can be used by a project’s <a class="reference internal" href="#entry-points">entry points</a> to specify dynamic
dependencies.  For example, if Project A includes a “rst2pdf” script, it might
declare it like this, so that the “PDF” requirements are only resolved if the
“rst2pdf” script is run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Project-A&quot;</span><span class="p">,</span>
    <span class="o">...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;console_scripts&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;rst2pdf = project_a.tools.pdfgen [PDF]&quot;</span><span class="p">,</span>
            <span class="s2">&quot;rst2html = project_a.tools.htmlgen&quot;</span><span class="p">,</span>
            <span class="c1"># more script entry points ...</span>
        <span class="p">],</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Projects can also use another project’s extras when specifying dependencies.
For example, if project B needs “project A” with PDF support installed, it
might declare the dependency like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Project-B&quot;</span><span class="p">,</span>
    <span class="n">install_requires</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;Project-A[PDF]&quot;</span><span class="p">],</span>
    <span class="o">...</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This will cause ReportLab to be installed along with project A, if project B is
installed – even if project A was already installed.  In this way, a project
can encapsulate groups of optional “downstream dependencies” under a feature
name, so that packages that depend on it don’t have to know what the downstream
dependencies are.  If a later version of Project A builds in PDF support and
no longer needs ReportLab, or if it ends up needing other dependencies besides
ReportLab in order to provide PDF support, Project B’s setup information does
not need to change, but the right packages will still be installed if needed.</p>
<p>Note, by the way, that if a project ends up not needing any other packages to
support a feature, it should keep an empty requirements list for that feature
in its <code class="docutils literal notranslate"><span class="pre">extras_require</span></code> argument, so that packages depending on that feature
don’t break (due to an invalid feature name).  For example, if Project A above
builds in PDF support and no longer needs ReportLab, it could change its
setup to this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Project-A&quot;</span><span class="p">,</span>
    <span class="o">...</span>
    <span class="n">extras_require</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;PDF&quot;</span><span class="p">:</span>  <span class="p">[],</span>
        <span class="s2">&quot;reST&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;docutils&gt;=0.3&quot;</span><span class="p">],</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>so that Package B doesn’t have to remove the <code class="docutils literal notranslate"><span class="pre">[PDF]</span></code> from its requirement
specifier.</p>
</div>
<div class="section" id="declaring-platform-specific-dependencies">
<span id="platform-specific-dependencies"></span><h5><a class="toc-backref" href="#id16">Declaring platform specific dependencies</a><a class="headerlink" href="#declaring-platform-specific-dependencies" title="Permalink to this headline">¶</a></h5>
<p>Sometimes a project might require a dependency to run on a specific platform.
This could to a package that back ports a module so that it can be used in
older python versions.  Or it could be a package that is required to run on a
specific operating system.  This will allow a project to work on multiple
different platforms without installing dependencies that are not required for
a platform that is installing the project.</p>
<p>For example, here is a project that uses the <code class="docutils literal notranslate"><span class="pre">enum</span></code> module and <code class="docutils literal notranslate"><span class="pre">pywin32</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Project&quot;</span><span class="p">,</span>
    <span class="o">...</span>
    <span class="n">install_requires</span><span class="o">=</span><span class="p">[</span>
        <span class="s2">&quot;enum34;python_version&lt;&#39;3.4&#39;&quot;</span><span class="p">,</span>
        <span class="s2">&quot;pywin32 &gt;= 1.0;platform_system==&#39;Windows&#39;&quot;</span>
    <span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Since the <code class="docutils literal notranslate"><span class="pre">enum</span></code> module was added in Python 3.4, it should only be installed
if the python version is earlier.  Since <code class="docutils literal notranslate"><span class="pre">pywin32</span></code> will only be used on
windows, it should only be installed when the operating system is Windows.
Specifying version requirements for the dependencies is supported as normal.</p>
<p>The environmental markers that may be used for testing platform types are
detailed in <a class="reference external" href="https://www.python.org/dev/peps/pep-0508/">PEP 508</a>.</p>
</div>
</div>
<div class="section" id="including-data-files">
<h4><a class="toc-backref" href="#id17">Including Data Files</a><a class="headerlink" href="#including-data-files" title="Permalink to this headline">¶</a></h4>
<p>The distutils have traditionally allowed installation of “data files”, which
are placed in a platform-specific location.  However, the most common use case
for data files distributed with a package is for use <em>by</em> the package, usually
by including the data files in the package directory.</p>
<p>Setuptools offers three ways to specify data files to be included in your
packages.  First, you can simply use the <code class="docutils literal notranslate"><span class="pre">include_package_data</span></code> keyword,
e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">include_package_data</span><span class="o">=</span><span class="kc">True</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This tells setuptools to install any data files it finds in your packages.
The data files must be specified via the distutils’ <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> file.
(They can also be tracked by a revision control system, using an appropriate
plugin.  See the section below on <a class="reference internal" href="#adding-support-for-revision-control-systems">Adding Support for Revision Control
Systems</a> for information on how to write such plugins.)</p>
<p>If you want finer-grained control over what files are included (for example,
if you have documentation files in your package directories and want to exclude
them from installation), then you can also use the <code class="docutils literal notranslate"><span class="pre">package_data</span></code> keyword,
e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">package_data</span><span class="o">=</span><span class="p">{</span>
        <span class="c1"># If any package contains *.txt or *.rst files, include them:</span>
        <span class="s2">&quot;&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;*.txt&quot;</span><span class="p">,</span> <span class="s2">&quot;*.rst&quot;</span><span class="p">],</span>
        <span class="c1"># And include any *.msg files found in the &quot;hello&quot; package, too:</span>
        <span class="s2">&quot;hello&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;*.msg&quot;</span><span class="p">],</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">package_data</span></code> argument is a dictionary that maps from package names to
lists of glob patterns.  The globs may include subdirectory names, if the data
files are contained in a subdirectory of the package.  For example, if the
package tree looks like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">src</span><span class="o">/</span>
    <span class="n">mypkg</span><span class="o">/</span>
        <span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
        <span class="n">mypkg</span><span class="o">.</span><span class="n">txt</span>
        <span class="n">data</span><span class="o">/</span>
            <span class="n">somefile</span><span class="o">.</span><span class="n">dat</span>
            <span class="n">otherdata</span><span class="o">.</span><span class="n">dat</span>
</pre></div>
</div>
<p>The setuptools setup file might look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">(</span><span class="s2">&quot;src&quot;</span><span class="p">),</span>  <span class="c1"># include all packages under src</span>
    <span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;&quot;</span><span class="p">:</span> <span class="s2">&quot;src&quot;</span><span class="p">},</span>   <span class="c1"># tell distutils packages are under src</span>

    <span class="n">package_data</span><span class="o">=</span><span class="p">{</span>
        <span class="c1"># If any package contains *.txt files, include them:</span>
        <span class="s2">&quot;&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;*.txt&quot;</span><span class="p">],</span>
        <span class="c1"># And include any *.dat files found in the &quot;data&quot; subdirectory</span>
        <span class="c1"># of the &quot;mypkg&quot; package, also:</span>
        <span class="s2">&quot;mypkg&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;data/*.dat&quot;</span><span class="p">],</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Notice that if you list patterns in <code class="docutils literal notranslate"><span class="pre">package_data</span></code> under the empty string,
these patterns are used to find files in every package, even ones that also
have their own patterns listed.  Thus, in the above example, the <code class="docutils literal notranslate"><span class="pre">mypkg.txt</span></code>
file gets included even though it’s not listed in the patterns for <code class="docutils literal notranslate"><span class="pre">mypkg</span></code>.</p>
<p>Also notice that if you use paths, you <em>must</em> use a forward slash (<code class="docutils literal notranslate"><span class="pre">/</span></code>) as
the path separator, even if you are on Windows.  Setuptools automatically
converts slashes to appropriate platform-specific separators at build time.</p>
<p>If datafiles are contained in a subdirectory of a package that isn’t a package
itself (no <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>), then the subdirectory names (or <code class="docutils literal notranslate"><span class="pre">*</span></code>) are required
in the <code class="docutils literal notranslate"><span class="pre">package_data</span></code> argument (as shown above with <code class="docutils literal notranslate"><span class="pre">&quot;data/*.dat&quot;</span></code>).</p>
<p>When building an <code class="docutils literal notranslate"><span class="pre">sdist</span></code>, the datafiles are also drawn from the
<code class="docutils literal notranslate"><span class="pre">package_name.egg-info/SOURCES.txt</span></code> file, so make sure that this is removed if
the <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> <code class="docutils literal notranslate"><span class="pre">package_data</span></code> list is updated before calling <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>.</p>
<p>(Note: although the <code class="docutils literal notranslate"><span class="pre">package_data</span></code> argument was previously only available in
<code class="docutils literal notranslate"><span class="pre">setuptools</span></code>, it was also added to the Python <code class="docutils literal notranslate"><span class="pre">distutils</span></code> package as of
Python 2.4; there is <a class="reference external" href="https://docs.python.org/3/distutils/setupscript.html#installing-package-data">some documentation for the feature</a> available on the
python.org website.  If using the setuptools-specific <code class="docutils literal notranslate"><span class="pre">include_package_data</span></code>
argument, files specified by <code class="docutils literal notranslate"><span class="pre">package_data</span></code> will <em>not</em> be automatically
added to the manifest unless they are listed in the MANIFEST.in file.)</p>
<p>Sometimes, the <code class="docutils literal notranslate"><span class="pre">include_package_data</span></code> or <code class="docutils literal notranslate"><span class="pre">package_data</span></code> options alone
aren’t sufficient to precisely define what files you want included.  For
example, you may want to include package README files in your revision control
system and source distributions, but exclude them from being installed.  So,
setuptools offers an <code class="docutils literal notranslate"><span class="pre">exclude_package_data</span></code> option as well, that allows you
to do things like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">(</span><span class="s2">&quot;src&quot;</span><span class="p">),</span>  <span class="c1"># include all packages under src</span>
    <span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;&quot;</span><span class="p">:</span> <span class="s2">&quot;src&quot;</span><span class="p">},</span>   <span class="c1"># tell distutils packages are under src</span>

    <span class="n">include_package_data</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>    <span class="c1"># include everything in source control</span>

    <span class="c1"># ...but exclude README.txt from all packages</span>
    <span class="n">exclude_package_data</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;README.txt&quot;</span><span class="p">]},</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">exclude_package_data</span></code> option is a dictionary mapping package names to
lists of wildcard patterns, just like the <code class="docutils literal notranslate"><span class="pre">package_data</span></code> option.  And, just
as with that option, a key of <code class="docutils literal notranslate"><span class="pre">&quot;&quot;</span></code> will apply the given pattern(s) to all
packages.  However, any files that match these patterns will be <em>excluded</em>
from installation, even if they were listed in <code class="docutils literal notranslate"><span class="pre">package_data</span></code> or were
included as a result of using <code class="docutils literal notranslate"><span class="pre">include_package_data</span></code>.</p>
<p>In summary, the three options allow you to:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">include_package_data</span></code></dt>
<dd>Accept all data files and directories matched by <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">package_data</span></code></dt>
<dd>Specify additional patterns to match files that may or may
not be matched by <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> or found in source control.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">exclude_package_data</span></code></dt>
<dd>Specify patterns for data files and directories that should <em>not</em> be
included when a package is installed, even if they would otherwise have
been included due to the use of the preceding options.</dd>
</dl>
<p>NOTE: Due to the way the distutils build process works, a data file that you
include in your project and then stop including may be “orphaned” in your
project’s build directories, requiring you to run <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">clean</span> <span class="pre">--all</span></code> to
fully remove them.  This may also be important for your users and contributors
if they track intermediate revisions of your project using Subversion; be sure
to let them know when you make changes that remove files from inclusion so they
can run <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">clean</span> <span class="pre">--all</span></code>.</p>
<div class="section" id="accessing-data-files-at-runtime">
<h5><a class="toc-backref" href="#id18">Accessing Data Files at Runtime</a><a class="headerlink" href="#accessing-data-files-at-runtime" title="Permalink to this headline">¶</a></h5>
<p>Typically, existing programs manipulate a package’s <code class="docutils literal notranslate"><span class="pre">__file__</span></code> attribute in
order to find the location of data files.  However, this manipulation isn’t
compatible with PEP 302-based import hooks, including importing from zip files
and Python Eggs.  It is strongly recommended that, if you are using data files,
you should use the <a class="reference internal" href="index.html#resourcemanager-api"><span class="std std-ref">ResourceManager API</span></a> of <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> to access
them.  The <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module is distributed as part of setuptools, so if
you’re using setuptools to distribute your package, there is no reason not to
use its resource management API.  See also <a class="reference external" href="https://docs.python.org/3/library/importlib.html#module-importlib.resources">Importlib Resources</a> for
a quick example of converting code that uses <code class="docutils literal notranslate"><span class="pre">__file__</span></code> to use
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> instead.</p>
</div>
<div class="section" id="non-package-data-files">
<h5><a class="toc-backref" href="#id19">Non-Package Data Files</a><a class="headerlink" href="#non-package-data-files" title="Permalink to this headline">¶</a></h5>
<p>Historically, <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> by way of <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> would encapsulate data
files from the distribution into the egg (see <a class="reference external" href="https://github.com/pypa/setuptools/blob/52aacd5b276fedd6849c3a648a0014f5da563e93/docs/setuptools.txt#L970-L1001">the old docs</a>). As eggs are deprecated and pip-based installs
fall back to the platform-specific location for installing data files, there is
no supported facility to reliably retrieve these resources.</p>
<p>Instead, the PyPA recommends that any data files you wish to be accessible at
run time be included in the package.</p>
</div>
<div class="section" id="automatic-resource-extraction">
<h5><a class="toc-backref" href="#id20">Automatic Resource Extraction</a><a class="headerlink" href="#automatic-resource-extraction" title="Permalink to this headline">¶</a></h5>
<p>If you are using tools that expect your resources to be “real” files, or your
project includes non-extension native libraries or other files that your C
extensions expect to be able to access, you may need to list those files in
the <code class="docutils literal notranslate"><span class="pre">eager_resources</span></code> argument to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>, so that the files will be
extracted together, whenever a C extension in the project is imported.</p>
<p>This is especially important if your project includes shared libraries <em>other</em>
than distutils-built C extensions, and those shared libraries use file
extensions other than <code class="docutils literal notranslate"><span class="pre">.dll</span></code>, <code class="docutils literal notranslate"><span class="pre">.so</span></code>, or <code class="docutils literal notranslate"><span class="pre">.dylib</span></code>, which are the
extensions that setuptools 0.6a8 and higher automatically detects as shared
libraries and adds to the <code class="docutils literal notranslate"><span class="pre">native_libs.txt</span></code> file for you.  Any shared
libraries whose names do not end with one of those extensions should be listed
as <code class="docutils literal notranslate"><span class="pre">eager_resources</span></code>, because they need to be present in the filesystem when
he C extensions that link to them are used.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> runtime for compressed packages will automatically
extract <em>all</em> C extensions and <code class="docutils literal notranslate"><span class="pre">eager_resources</span></code> at the same time, whenever
<em>any</em> C extension or eager resource is requested via the <code class="docutils literal notranslate"><span class="pre">resource_filename()</span></code>
API.  (C extensions are imported using <code class="docutils literal notranslate"><span class="pre">resource_filename()</span></code> internally.)
This ensures that C extensions will see all of the “real” files that they
expect to see.</p>
<p>Note also that you can list directory resource names in <code class="docutils literal notranslate"><span class="pre">eager_resources</span></code> as
well, in which case the directory’s contents (including subdirectories) will be
extracted whenever any C extension or eager resource is requested.</p>
<p>Please note that if you’re not sure whether you need to use this argument, you
don’t!  It’s really intended to support projects with lots of non-Python
dependencies and as a last resort for crufty projects that can’t otherwise
handle being compressed.  If your package is pure Python, Python plus data
files, or Python plus C, you really don’t need this.  You’ve got to be using
either C or an external program that needs “real” files in your project before
there’s any possibility of <code class="docutils literal notranslate"><span class="pre">eager_resources</span></code> being relevant to your project.</p>
</div>
</div>
<div class="section" id="extensible-applications-and-frameworks">
<h4><a class="toc-backref" href="#id21">Extensible Applications and Frameworks</a><a class="headerlink" href="#extensible-applications-and-frameworks" title="Permalink to this headline">¶</a></h4>
<div class="section" id="dynamic-discovery-of-services-and-plugins">
<span id="entry-points"></span><h5><a class="toc-backref" href="#id22">Dynamic Discovery of Services and Plugins</a><a class="headerlink" href="#dynamic-discovery-of-services-and-plugins" title="Permalink to this headline">¶</a></h5>
<p><code class="docutils literal notranslate"><span class="pre">setuptools</span></code> supports creating libraries that “plug in” to extensible
applications and frameworks, by letting you register “entry points” in your
project that can be imported by the application or framework.</p>
<p>For example, suppose that a blogging tool wants to support plugins
that provide translation for various file types to the blog’s output format.
The framework might define an “entry point group” called <code class="docutils literal notranslate"><span class="pre">blogtool.parsers</span></code>,
and then allow plugins to register entry points for the file extensions they
support.</p>
<p>This would allow people to create distributions that contain one or more
parsers for different file types, and then the blogging tool would be able to
find the parsers at runtime by looking up an entry point for the file
extension (or mime type, or however it wants to).</p>
<p>Note that if the blogging tool includes parsers for certain file formats, it
can register these as entry points in its own setup script, which means it
doesn’t have to special-case its built-in formats.  They can just be treated
the same as any other plugin’s entry points would be.</p>
<p>If you’re creating a project that plugs in to an existing application or
framework, you’ll need to know what entry points or entry point groups are
defined by that application or framework.  Then, you can register entry points
in your setup script.  Here are a few examples of ways you might register an
<code class="docutils literal notranslate"><span class="pre">.rst</span></code> file parser entry point in the <code class="docutils literal notranslate"><span class="pre">blogtool.parsers</span></code> entry point group,
for our hypothetical blogging tool:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;blogtool.parsers&quot;</span><span class="p">:</span> <span class="s2">&quot;.rst = some_module:SomeClass&quot;</span><span class="p">}</span>
<span class="p">)</span>

<span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;blogtool.parsers&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;.rst = some_module:a_func&quot;</span><span class="p">]}</span>
<span class="p">)</span>

<span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="s2">&quot;&quot;&quot;</span>
<span class="s2">        [blogtool.parsers]</span>
<span class="s2">        .rst = some.nested.module:SomeClass.some_classmethod [reST]</span>
<span class="s2">    &quot;&quot;&quot;</span><span class="p">,</span>
    <span class="n">extras_require</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">reST</span><span class="o">=</span><span class="s2">&quot;Docutils&gt;=0.3.5&quot;</span><span class="p">)</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">entry_points</span></code> argument to <code class="docutils literal notranslate"><span class="pre">setup()</span></code> accepts either a string with
<code class="docutils literal notranslate"><span class="pre">.ini</span></code>-style sections, or a dictionary mapping entry point group names to
either strings or lists of strings containing entry point specifiers.  An
entry point specifier consists of a name and value, separated by an <code class="docutils literal notranslate"><span class="pre">=</span></code>
sign.  The value consists of a dotted module name, optionally followed by a
<code class="docutils literal notranslate"><span class="pre">:</span></code> and a dotted identifier naming an object within the module.  It can
also include a bracketed list of “extras” that are required for the entry
point to be used.  When the invoking application or framework requests loading
of an entry point, any requirements implied by the associated extras will be
passed to <code class="docutils literal notranslate"><span class="pre">pkg_resources.require()</span></code>, so that an appropriate error message
can be displayed if the needed package(s) are missing.  (Of course, the
invoking app or framework can ignore such errors if it wants to make an entry
point optional if a requirement isn’t installed.)</p>
</div>
<div class="section" id="defining-additional-metadata">
<h5><a class="toc-backref" href="#id23">Defining Additional Metadata</a><a class="headerlink" href="#defining-additional-metadata" title="Permalink to this headline">¶</a></h5>
<p>Some extensible applications and frameworks may need to define their own kinds
of metadata to include in eggs, which they can then access using the
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> metadata APIs.  Ordinarily, this is done by having plugin
developers include additional files in their <code class="docutils literal notranslate"><span class="pre">ProjectName.egg-info</span></code>
directory.  However, since it can be tedious to create such files by hand, you
may want to create a distutils extension that will create the necessary files
from arguments to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>, in much the same way that <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> does
for many of the <code class="docutils literal notranslate"><span class="pre">setup()</span></code> arguments it adds.  See the section below on
<a class="reference internal" href="#creating-distutils-extensions">Creating distutils Extensions</a> for more details, especially the subsection on
<a class="reference internal" href="#adding-new-egg-info-files">Adding new EGG-INFO Files</a>.</p>
</div>
</div>
<div class="section" id="development-mode">
<h4><a class="toc-backref" href="#id24">“Development Mode”</a><a class="headerlink" href="#development-mode" title="Permalink to this headline">¶</a></h4>
<p>Under normal circumstances, the <code class="docutils literal notranslate"><span class="pre">distutils</span></code> assume that you are going to
build a distribution of your project, not use it in its “raw” or “unbuilt”
form.  If you were to use the <code class="docutils literal notranslate"><span class="pre">distutils</span></code> that way, you would have to rebuild
and reinstall your project every time you made a change to it during
development.</p>
<p>Another problem that sometimes comes up with the <code class="docutils literal notranslate"><span class="pre">distutils</span></code> is that you may
need to do development on two related projects at the same time.  You may need
to put both projects’ packages in the same directory to run them, but need to
keep them separate for revision control purposes.  How can you do this?</p>
<p>Setuptools allows you to deploy your projects for use in a common directory or
staging area, but without copying any files.  Thus, you can edit each project’s
code in its checkout directory, and only need to run build commands when you
change a project’s C extensions or similarly compiled files.  You can even
deploy a project into another project’s checkout directory, if that’s your
preferred way of working (as opposed to using a common independent staging area
or the site-packages directory).</p>
<p>To do this, use the <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code> command.  It works very similarly to
<code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">install</span></code>, except that it doesn’t actually install anything.
Instead, it creates a special <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> file in the deployment directory,
that links to your project’s source code.  And, if your deployment directory is
Python’s <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory, it will also update the
<code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> file to include your project’s source code, thereby making
it available on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> for all programs using that Python installation.</p>
<p>If you have enabled the <code class="docutils literal notranslate"><span class="pre">use_2to3</span></code> flag, then of course the <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code>
will not link directly to your source code when run under Python 3, since
that source code would be made for Python 2 and not work under Python 3.
Instead the <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code> will build Python 3 code under the <code class="docutils literal notranslate"><span class="pre">build</span></code>
directory, and link there. This means that after doing code changes you will
have to run <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">build</span></code> before these changes are picked up by your
Python 3 installation.</p>
<p>In addition, the <code class="docutils literal notranslate"><span class="pre">develop</span></code> command creates wrapper scripts in the target
script directory that will run your in-development scripts after ensuring that
all your <code class="docutils literal notranslate"><span class="pre">install_requires</span></code> packages are available on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.</p>
<p>You can deploy the same project to multiple staging areas, e.g. if you have
multiple projects on the same machine that are sharing the same project you’re
doing development work.</p>
<p>When you’re done with a given development task, you can remove the project
source from a staging area using <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span> <span class="pre">--uninstall</span></code>, specifying
the desired staging area if it’s not the default.</p>
<p>There are several options to control the precise behavior of the <code class="docutils literal notranslate"><span class="pre">develop</span></code>
command; see the section on the <a class="reference internal" href="#develop">develop</a> command below for more details.</p>
<p>Note that you can also apply setuptools commands to non-setuptools projects,
using commands like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">c</span> <span class="s2">&quot;import setuptools; with open(&#39;setup.py&#39;) as f: exec(compile(f.read(), &#39;setup.py&#39;, &#39;exec&#39;))&quot;</span> <span class="n">develop</span>
</pre></div>
</div>
<p>That is, you can simply list the normal setup commands and options following
the quoted part.</p>
</div>
<div class="section" id="distributing-a-setuptools-based-project">
<h4><a class="toc-backref" href="#id25">Distributing a <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>-based project</a><a class="headerlink" href="#distributing-a-setuptools-based-project" title="Permalink to this headline">¶</a></h4>
<p>Detailed instructions to distribute a setuptools project can be found at
<a class="reference external" href="https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives">Packaging project tutorials</a>.</p>
<p>Before you begin, make sure you have the latest versions of setuptools and wheel:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">setuptools</span> <span class="n">wheel</span>
</pre></div>
</div>
<p>To build a setuptools project, run this command from the same directory where
setup.py is located:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span> <span class="n">bdist_wheel</span>
</pre></div>
</div>
<p>This will generate distribution archives in the <cite>dist</cite> directory.</p>
<p>Before you upload the generated archives make sure you’re registered on
<a class="reference external" href="https://test.pypi.org/account/register/">https://test.pypi.org/account/register/</a>. You will also need to verify your email
to be able to upload any packages.
You should install twine to be able to upload packages:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">twine</span>
</pre></div>
</div>
<p>Now, to upload these archives, run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">twine</span> <span class="n">upload</span> <span class="o">--</span><span class="n">repository</span><span class="o">-</span><span class="n">url</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">test</span><span class="o">.</span><span class="n">pypi</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">legacy</span><span class="o">/</span> <span class="n">dist</span><span class="o">/*</span>
</pre></div>
</div>
<p>To install your newly uploaded package <code class="docutils literal notranslate"><span class="pre">example_pkg</span></code>,  you can use pip:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">index</span><span class="o">-</span><span class="n">url</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">test</span><span class="o">.</span><span class="n">pypi</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">simple</span><span class="o">/</span> <span class="n">example_pkg</span>
</pre></div>
</div>
<p>If you have issues at any point, please refer to <a class="reference external" href="https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives">Packaging project tutorials</a>
for clarification.</p>
<div class="section" id="setting-the-zip-safe-flag">
<h5><a class="toc-backref" href="#id26">Setting the <code class="docutils literal notranslate"><span class="pre">zip_safe</span></code> flag</a><a class="headerlink" href="#setting-the-zip-safe-flag" title="Permalink to this headline">¶</a></h5>
<p>For some use cases (such as bundling as part of a larger application), Python
packages may be run directly from a zip file.
Not all packages, however, are capable of running in compressed form, because
they may expect to be able to access either source code or data files as
normal operating system files.  So, <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> can install your project
as a zipfile or a directory, and its default choice is determined by the
project’s <code class="docutils literal notranslate"><span class="pre">zip_safe</span></code> flag.</p>
<p>You can pass a True or False value for the <code class="docutils literal notranslate"><span class="pre">zip_safe</span></code> argument to the
<code class="docutils literal notranslate"><span class="pre">setup()</span></code> function, or you can omit it.  If you omit it, the <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code>
command will analyze your project’s contents to see if it can detect any
conditions that would prevent it from working in a zipfile.  It will output
notices to the console about any such conditions that it finds.</p>
<p>Currently, this analysis is extremely conservative: it will consider the
project unsafe if it contains any C extensions or datafiles whatsoever.  This
does <em>not</em> mean that the project can’t or won’t work as a zipfile!  It just
means that the <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> authors aren’t yet comfortable asserting that
the project <em>will</em> work.  If the project contains no C or data files, and does
no <code class="docutils literal notranslate"><span class="pre">__file__</span></code> or <code class="docutils literal notranslate"><span class="pre">__path__</span></code> introspection or source code manipulation, then
there is an extremely solid chance the project will work when installed as a
zipfile.  (And if the project uses <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> for all its data file
access, then C extensions and other data files shouldn’t be a problem at all.
See the <a class="reference internal" href="#accessing-data-files-at-runtime">Accessing Data Files at Runtime</a> section above for more information.)</p>
<p>However, if <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> can’t be <em>sure</em> that your package will work, but
you’ve checked over all the warnings it issued, and you are either satisfied it
<em>will</em> work (or if you want to try it for yourself), then you should set
<code class="docutils literal notranslate"><span class="pre">zip_safe</span></code> to <code class="docutils literal notranslate"><span class="pre">True</span></code> in your <code class="docutils literal notranslate"><span class="pre">setup()</span></code> call.  If it turns out that it
doesn’t work, you can always change it to <code class="docutils literal notranslate"><span class="pre">False</span></code>, which will force
<code class="docutils literal notranslate"><span class="pre">setuptools</span></code> to install your project as a directory rather than as a zipfile.</p>
<p>In the future, as we gain more experience with different packages and become
more satisfied with the robustness of the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> runtime, the
“zip safety” analysis may become less conservative.  However, we strongly
recommend that you determine for yourself whether your project functions
correctly when installed as a zipfile, correct any problems if you can, and
then make an explicit declaration of <code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">False</span></code> for the <code class="docutils literal notranslate"><span class="pre">zip_safe</span></code>
flag, so that it will not be necessary for <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> to try to guess
whether your project can work as a zipfile.</p>
</div>
<div class="section" id="namespace-packages">
<span id="id2"></span><h5><a class="toc-backref" href="#id27">Namespace Packages</a><a class="headerlink" href="#namespace-packages" title="Permalink to this headline">¶</a></h5>
<p>Sometimes, a large package is more useful if distributed as a collection of
smaller eggs.  However, Python does not normally allow the contents of a
package to be retrieved from more than one location.  “Namespace packages”
are a solution for this problem.  When you declare a package to be a namespace
package, it means that the package has no meaningful contents in its
<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>, and that it is merely a container for modules and subpackages.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> runtime will then automatically ensure that the contents
of namespace packages that are spread over multiple eggs or directories are
combined into a single “virtual” package.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">namespace_packages</span></code> argument to <code class="docutils literal notranslate"><span class="pre">setup()</span></code> lets you declare your
project’s namespace packages, so that they will be included in your project’s
metadata.  The argument should list the namespace packages that the egg
participates in.  For example, the ZopeInterface project might do this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">namespace_packages</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;zope&quot;</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<p>because it contains a <code class="docutils literal notranslate"><span class="pre">zope.interface</span></code> package that lives in the <code class="docutils literal notranslate"><span class="pre">zope</span></code>
namespace package.  Similarly, a project for a standalone <code class="docutils literal notranslate"><span class="pre">zope.publisher</span></code>
would also declare the <code class="docutils literal notranslate"><span class="pre">zope</span></code> namespace package.  When these projects are
installed and used, Python will see them both as part of a “virtual” <code class="docutils literal notranslate"><span class="pre">zope</span></code>
package, even though they will be installed in different locations.</p>
<p>Namespace packages don’t have to be top-level packages.  For example, Zope 3’s
<code class="docutils literal notranslate"><span class="pre">zope.app</span></code> package is a namespace package, and in the future PEAK’s
<code class="docutils literal notranslate"><span class="pre">peak.util</span></code> package will be too.</p>
<p>Note, by the way, that your project’s source tree must include the namespace
packages’ <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files (and the <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> of any parent
packages), in a normal Python package layout.  These <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files
<em>must</em> contain the line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">__import__</span><span class="p">(</span><span class="s2">&quot;pkg_resources&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">declare_namespace</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>
</pre></div>
</div>
<p>This code ensures that the namespace package machinery is operating and that
the current package is registered as a namespace package.</p>
<p>You must NOT include any other code and data in a namespace package’s
<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>.  Even though it may appear to work during development, or when
projects are installed as <code class="docutils literal notranslate"><span class="pre">.egg</span></code> files, it will not work when the projects
are installed using “system” packaging tools – in such cases the
<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files will not be installed, let alone executed.</p>
<p>You must include the <code class="docutils literal notranslate"><span class="pre">declare_namespace()</span></code>  line in the <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> of
<em>every</em> project that has contents for the namespace package in question, in
order to ensure that the namespace will be declared regardless of which
project’s copy of <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> is loaded first.  If the first loaded
<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> doesn’t declare it, it will never <em>be</em> declared, because no
other copies will ever be loaded!</p>
<div class="section" id="transitional-note">
<h6><a class="toc-backref" href="#id28">TRANSITIONAL NOTE</a><a class="headerlink" href="#transitional-note" title="Permalink to this headline">¶</a></h6>
<p>Setuptools automatically calls <code class="docutils literal notranslate"><span class="pre">declare_namespace()</span></code> for you at runtime,
but future versions may <em>not</em>.  This is because the automatic declaration
feature has some negative side effects, such as needing to import all namespace
packages during the initialization of the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> runtime, and also
the need for <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> to be explicitly imported before any namespace
packages work at all.  In some future releases, you’ll be responsible
for including your own declaration lines, and the automatic declaration feature
will be dropped to get rid of the negative side effects.</p>
<p>During the remainder of the current development cycle, therefore, setuptools
will warn you about missing <code class="docutils literal notranslate"><span class="pre">declare_namespace()</span></code> calls in your
<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files, and you should correct these as soon as possible
before the compatibility support is removed.
Namespace packages without declaration lines will not work
correctly once a user has upgraded to a later version, so it’s important that
you make this change now in order to avoid having your code break in the field.
Our apologies for the inconvenience, and thank you for your patience.</p>
</div>
</div>
<div class="section" id="tagging-and-daily-build-or-snapshot-releases">
<h5><a class="toc-backref" href="#id29">Tagging and “Daily Build” or “Snapshot” Releases</a><a class="headerlink" href="#tagging-and-daily-build-or-snapshot-releases" title="Permalink to this headline">¶</a></h5>
<p>When a set of related projects are under development, it may be important to
track finer-grained version increments than you would normally use for e.g.
“stable” releases.  While stable releases might be measured in dotted numbers
with alpha/beta/etc. status codes, development versions of a project often
need to be tracked by revision or build number or even build date.  This is
especially true when projects in development need to refer to one another, and
therefore may literally need an up-to-the-minute version of something!</p>
<p>To support these scenarios, <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> allows you to “tag” your source and
egg distributions by adding one or more of the following to the project’s
“official” version identifier:</p>
<ul class="simple">
<li>A manually-specified pre-release tag, such as “build” or “dev”, or a
manually-specified post-release tag, such as a build or revision number
(<code class="docutils literal notranslate"><span class="pre">--tag-build=STRING,</span> <span class="pre">-bSTRING</span></code>)</li>
<li>An 8-character representation of the build date (<code class="docutils literal notranslate"><span class="pre">--tag-date,</span> <span class="pre">-d</span></code>), as
a postrelease tag</li>
</ul>
<p>You can add these tags by adding <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> and the desired options to
the command line ahead of the <code class="docutils literal notranslate"><span class="pre">sdist</span></code> or <code class="docutils literal notranslate"><span class="pre">bdist</span></code> commands that you want
to generate a daily build or snapshot for.  See the section below on the
<a class="reference internal" href="#egg-info">egg_info</a> command for more details.</p>
<p>(Also, before you release your project, be sure to see the section above on
<a class="reference internal" href="#specifying-your-project-s-version">Specifying Your Project’s Version</a> for more information about how pre- and
post-release tags affect how version numbers are interpreted.  This is
important in order to make sure that dependency processing tools will know
which versions of your project are newer than others.)</p>
<p>Finally, if you are creating builds frequently, and either building them in a
downloadable location or are copying them to a distribution server, you should
probably also check out the <a class="reference internal" href="#rotate">rotate</a> command, which lets you automatically
delete all but the N most-recently-modified distributions matching a glob
pattern.  So, you can use a command line like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">egg_info</span> <span class="o">-</span><span class="n">rbDEV</span> <span class="n">bdist_egg</span> <span class="n">rotate</span> <span class="o">-</span><span class="n">m</span><span class="o">.</span><span class="n">egg</span> <span class="o">-</span><span class="n">k3</span>
</pre></div>
</div>
<p>to build an egg whose version info includes “DEV-rNNNN” (where NNNN is the
most recent Subversion revision that affected the source tree), and then
delete any egg files from the distribution directory except for the three
that were built most recently.</p>
<p>If you have to manage automated builds for multiple packages, each with
different tagging and rotation policies, you may also want to check out the
<a class="reference internal" href="#alias">alias</a> command, which would let each package define an alias like <code class="docutils literal notranslate"><span class="pre">daily</span></code>
that would perform the necessary tag, build, and rotate commands.  Then, a
simpler script or cron job could just run <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">daily</span></code> in each project
directory.  (And, you could also define sitewide or per-user default versions
of the <code class="docutils literal notranslate"><span class="pre">daily</span></code> alias, so that projects that didn’t define their own would
use the appropriate defaults.)</p>
</div>
<div class="section" id="generating-source-distributions">
<h5><a class="toc-backref" href="#id30">Generating Source Distributions</a><a class="headerlink" href="#generating-source-distributions" title="Permalink to this headline">¶</a></h5>
<p><code class="docutils literal notranslate"><span class="pre">setuptools</span></code> enhances the distutils’ default algorithm for source file
selection with pluggable endpoints for looking up files to include. If you are
using a revision control system, and your source distributions only need to
include files that you’re tracking in revision control, use a corresponding
plugin instead of writing a <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> file. See the section below on
<a class="reference internal" href="#adding-support-for-revision-control-systems">Adding Support for Revision Control Systems</a> for information on plugins.</p>
<p>If you need to include automatically generated files, or files that are kept in
an unsupported revision control system, you’ll need to create a <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code>
file to specify any files that the default file location algorithm doesn’t
catch.  See the distutils documentation for more information on the format of
the <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> file.</p>
<p>But, be sure to ignore any part of the distutils documentation that deals with
<code class="docutils literal notranslate"><span class="pre">MANIFEST</span></code> or how it’s generated from <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code>; setuptools shields you
from these issues and doesn’t work the same way in any case.  Unlike the
distutils, setuptools regenerates the source distribution manifest file
every time you build a source distribution, and it builds it inside the
project’s <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> directory, out of the way of your main project
directory.  You therefore need not worry about whether it is up-to-date or not.</p>
<p>Indeed, because setuptools’ approach to determining the contents of a source
distribution is so much simpler, its <code class="docutils literal notranslate"><span class="pre">sdist</span></code> command omits nearly all of
the options that the distutils’ more complex <code class="docutils literal notranslate"><span class="pre">sdist</span></code> process requires.  For
all practical purposes, you’ll probably use only the <code class="docutils literal notranslate"><span class="pre">--formats</span></code> option, if
you use any option at all.</p>
<div class="section" id="making-official-non-snapshot-releases">
<h6><a class="toc-backref" href="#id31">Making “Official” (Non-Snapshot) Releases</a><a class="headerlink" href="#making-official-non-snapshot-releases" title="Permalink to this headline">¶</a></h6>
<p>When you make an official release, creating source or binary distributions,
you will need to override the tag settings from <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>, so that you
don’t end up registering versions like <code class="docutils literal notranslate"><span class="pre">foobar-0.7a1.dev-r34832</span></code>.  This is
easy to do if you are developing on the trunk and using tags or branches for
your releases - just make the change to <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> after branching or
tagging the release, so the trunk will still produce development snapshots.</p>
<p>Alternately, if you are not branching for releases, you can override the
default version options on the command line, using something like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">egg_info</span> <span class="o">-</span><span class="n">Db</span> <span class="s2">&quot;&quot;</span> <span class="n">sdist</span> <span class="n">bdist_egg</span>
</pre></div>
</div>
<p>The first part of this command (<code class="docutils literal notranslate"><span class="pre">egg_info</span> <span class="pre">-Db</span> <span class="pre">&quot;&quot;</span></code>) will override the
configured tag information, before creating source and binary eggs. Thus, these
commands will use the plain version from your <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>, without adding the
build designation string.</p>
<p>Of course, if you will be doing this a lot, you may wish to create a personal
alias for this operation, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">alias</span> <span class="o">-</span><span class="n">u</span> <span class="n">release</span> <span class="n">egg_info</span> <span class="o">-</span><span class="n">Db</span> <span class="s2">&quot;&quot;</span>
</pre></div>
</div>
<p>You can then use it like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">release</span> <span class="n">sdist</span> <span class="n">bdist_egg</span>
</pre></div>
</div>
<p>Or of course you can create more elaborate aliases that do all of the above.
See the sections below on the <a class="reference internal" href="#egg-info">egg_info</a> and <a class="reference internal" href="#alias">alias</a> commands for more ideas.</p>
</div>
</div>
<div class="section" id="distributing-extensions-compiled-with-cython">
<h5><a class="toc-backref" href="#id32">Distributing Extensions compiled with Cython</a><a class="headerlink" href="#distributing-extensions-compiled-with-cython" title="Permalink to this headline">¶</a></h5>
<p><code class="docutils literal notranslate"><span class="pre">setuptools</span></code> will detect at build time whether Cython is installed or not.
If Cython is not found <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> will ignore pyx files.</p>
<p>To ensure Cython is available, include Cython in the build-requires section
of your pyproject.toml:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">build</span><span class="o">-</span><span class="n">system</span><span class="p">]</span>
<span class="n">requires</span><span class="o">=</span><span class="p">[</span><span class="o">...</span><span class="p">,</span> <span class="s2">&quot;cython&quot;</span><span class="p">]</span>
</pre></div>
</div>
<p>Built with pip 10 or later, that declaration is sufficient to include Cython
in the build. For broader compatibility, declare the dependency in your
setup-requires of setup.cfg:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">options</span><span class="p">]</span>
<span class="n">setup_requires</span> <span class="o">=</span>
    <span class="o">...</span>
    <span class="n">cython</span>
</pre></div>
</div>
<p>As long as Cython is present in the build environment, <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> includes
transparent support for building Cython extensions, as
long as extensions are defined using <code class="docutils literal notranslate"><span class="pre">setuptools.Extension</span></code>.</p>
<p>If you follow these rules, you can safely list <code class="docutils literal notranslate"><span class="pre">.pyx</span></code> files as the source
of your <code class="docutils literal notranslate"><span class="pre">Extension</span></code> objects in the setup script.  If it is, then <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>
will use it.</p>
<p>Of course, for this to work, your source distributions must include the C
code generated by Cython, as well as your original <code class="docutils literal notranslate"><span class="pre">.pyx</span></code> files.  This means
that you will probably want to include current <code class="docutils literal notranslate"><span class="pre">.c</span></code> files in your revision
control system, rebuilding them whenever you check changes in for the <code class="docutils literal notranslate"><span class="pre">.pyx</span></code>
source files.  This will ensure that people tracking your project in a revision
control system will be able to build it even if they don’t have Cython
installed, and that your source releases will be similarly usable with or
without Cython.</p>
</div>
</div>
</div>
<div class="section" id="command-reference">
<h3><a class="toc-backref" href="#id33">Command Reference</a><a class="headerlink" href="#command-reference" title="Permalink to this headline">¶</a></h3>
<div class="section" id="alias-define-shortcuts-for-commonly-used-commands">
<span id="alias"></span><h4><a class="toc-backref" href="#id34"><code class="docutils literal notranslate"><span class="pre">alias</span></code> - Define shortcuts for commonly used commands</a><a class="headerlink" href="#alias-define-shortcuts-for-commonly-used-commands" title="Permalink to this headline">¶</a></h4>
<p>Sometimes, you need to use the same commands over and over, but you can’t
necessarily set them as defaults.  For example, if you produce both development
snapshot releases and “stable” releases of a project, you may want to put
the distributions in different places, or use different <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> tagging
options, etc.  In these cases, it doesn’t make sense to set the options in
a distutils configuration file, because the values of the options changed based
on what you’re trying to do.</p>
<p>Setuptools therefore allows you to define “aliases” - shortcut names for
an arbitrary string of commands and options, using <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">alias</span> <span class="pre">aliasname</span>
<span class="pre">expansion</span></code>, where aliasname is the name of the new alias, and the remainder of
the command line supplies its expansion.  For example, this command defines
a sitewide alias called “daily”, that sets various <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> tagging
options:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">alias</span> <span class="o">--</span><span class="k">global</span><span class="o">-</span><span class="n">config</span> <span class="n">daily</span> <span class="n">egg_info</span> <span class="o">--</span><span class="n">tag</span><span class="o">-</span><span class="n">build</span><span class="o">=</span><span class="n">development</span>
</pre></div>
</div>
<p>Once the alias is defined, it can then be used with other setup commands,
e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">daily</span> <span class="n">bdist_egg</span>        <span class="c1"># generate a daily-build .egg file</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">daily</span> <span class="n">sdist</span>            <span class="c1"># generate a daily-build source distro</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">daily</span> <span class="n">sdist</span> <span class="n">bdist_egg</span>  <span class="c1"># generate both</span>
</pre></div>
</div>
<p>The above commands are interpreted as if the word <code class="docutils literal notranslate"><span class="pre">daily</span></code> were replaced with
<code class="docutils literal notranslate"><span class="pre">egg_info</span> <span class="pre">--tag-build=development</span></code>.</p>
<p>Note that setuptools will expand each alias <em>at most once</em> in a given command
line.  This serves two purposes.  First, if you accidentally create an alias
loop, it will have no effect; you’ll instead get an error message about an
unknown command.  Second, it allows you to define an alias for a command, that
uses that command.  For example, this (project-local) alias:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">alias</span> <span class="n">bdist_egg</span> <span class="n">bdist_egg</span> <span class="n">rotate</span> <span class="o">-</span><span class="n">k1</span> <span class="o">-</span><span class="n">m</span><span class="o">.</span><span class="n">egg</span>
</pre></div>
</div>
<p>redefines the <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> command so that it always runs the <code class="docutils literal notranslate"><span class="pre">rotate</span></code>
command afterwards to delete all but the newest egg file.  It doesn’t loop
indefinitely on <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> because the alias is only expanded once when
used.</p>
<p>You can remove a defined alias with the <code class="docutils literal notranslate"><span class="pre">--remove</span></code> (or <code class="docutils literal notranslate"><span class="pre">-r</span></code>) option, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">alias</span> <span class="o">--</span><span class="k">global</span><span class="o">-</span><span class="n">config</span> <span class="o">--</span><span class="n">remove</span> <span class="n">daily</span>
</pre></div>
</div>
<p>would delete the “daily” alias we defined above.</p>
<p>Aliases can be defined on a project-specific, per-user, or sitewide basis.  The
default is to define or remove a project-specific alias, but you can use any of
the <a class="reference internal" href="#configuration-file-options">configuration file options</a> (listed under the <a class="reference internal" href="#saveopts">saveopts</a> command, below)
to determine which distutils configuration file an aliases will be added to
(or removed from).</p>
<p>Note that if you omit the “expansion” argument to the <code class="docutils literal notranslate"><span class="pre">alias</span></code> command,
you’ll get output showing that alias’ current definition (and what
configuration file it’s defined in).  If you omit the alias name as well,
you’ll get a listing of all current aliases along with their configuration
file locations.</p>
</div>
<div class="section" id="bdist-egg-create-a-python-egg-for-the-project">
<h4><a class="toc-backref" href="#id35"><code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> - Create a Python Egg for the project</a><a class="headerlink" href="#bdist-egg-create-a-python-egg-for-the-project" title="Permalink to this headline">¶</a></h4>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last"><strong>eggs</strong> are deprecated in favor of wheels, and not supported by pip.</p>
</div>
<p>This command generates a Python Egg (<code class="docutils literal notranslate"><span class="pre">.egg</span></code> file) for the project.  Python
Eggs are the preferred binary distribution format for EasyInstall, because they
are cross-platform (for “pure” packages), directly importable, and contain
project metadata including scripts and information about the project’s
dependencies.  They can be simply downloaded and added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>
directly, or they can be placed in a directory on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> and then
automatically discovered by the egg runtime system.</p>
<p>This command runs the <a class="reference internal" href="#egg-info">egg_info</a> command (if it hasn’t already run) to update
the project’s metadata (<code class="docutils literal notranslate"><span class="pre">.egg-info</span></code>) directory.  If you have added any extra
metadata files to the <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> directory, those files will be included in
the new egg file’s metadata directory, for use by the egg runtime system or by
any applications or frameworks that use that metadata.</p>
<p>You won’t usually need to specify any special options for this command; just
use <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> and you’re done.  But there are a few options that may
be occasionally useful:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">--dist-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></code></dt>
<dd>Set the directory where the <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file will be placed.  If you don’t
supply this, then the <code class="docutils literal notranslate"><span class="pre">--dist-dir</span></code> setting of the <code class="docutils literal notranslate"><span class="pre">bdist</span></code> command
will be used, which is usually a directory named <code class="docutils literal notranslate"><span class="pre">dist</span></code> in the project
directory.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--plat-name=PLATFORM,</span> <span class="pre">-p</span> <span class="pre">PLATFORM</span></code></dt>
<dd>Set the platform name string that will be embedded in the egg’s filename
(assuming the egg contains C extensions).  This can be used to override
the distutils default platform name with something more meaningful.  Keep
in mind, however, that the egg runtime system expects to see eggs with
distutils platform names, so it may ignore or reject eggs with non-standard
platform names.  Similarly, the EasyInstall program may ignore them when
searching web pages for download links.  However, if you are
cross-compiling or doing some other unusual things, you might find a use
for this option.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--exclude-source-files</span></code></dt>
<dd>Don’t include any modules’ <code class="docutils literal notranslate"><span class="pre">.py</span></code> files in the egg, just compiled Python,
C, and data files.  (Note that this doesn’t affect any <code class="docutils literal notranslate"><span class="pre">.py</span></code> files in the
EGG-INFO directory or its subdirectories, since for example there may be
scripts with a <code class="docutils literal notranslate"><span class="pre">.py</span></code> extension which must still be retained.)  We don’t
recommend that you use this option except for packages that are being
bundled for proprietary end-user applications, or for “embedded” scenarios
where space is at an absolute premium.  On the other hand, if your package
is going to be installed and used in compressed form, you might as well
exclude the source because Python’s <code class="docutils literal notranslate"><span class="pre">traceback</span></code> module doesn’t currently
understand how to display zipped source code anyway, or how to deal with
files that are in a different place from where their code was compiled.</dd>
</dl>
<p>There are also some options you will probably never need, but which are there
because they were copied from similar <code class="docutils literal notranslate"><span class="pre">bdist</span></code> commands used as an example for
creating this one.  They may be useful for testing and debugging, however,
which is why we kept them:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">--keep-temp,</span> <span class="pre">-k</span></code></dt>
<dd>Keep the contents of the <code class="docutils literal notranslate"><span class="pre">--bdist-dir</span></code> tree around after creating the
<code class="docutils literal notranslate"><span class="pre">.egg</span></code> file.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--bdist-dir=DIR,</span> <span class="pre">-b</span> <span class="pre">DIR</span></code></dt>
<dd>Set the temporary directory for creating the distribution.  The entire
contents of this directory are zipped to create the <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file, after
running various installation commands to copy the package’s modules, data,
and extensions here.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--skip-build</span></code></dt>
<dd>Skip doing any “build” commands; just go straight to the
install-and-compress phases.</dd>
</dl>
</div>
<div class="section" id="develop-deploy-the-project-source-in-development-mode">
<span id="develop"></span><h4><a class="toc-backref" href="#id36"><code class="docutils literal notranslate"><span class="pre">develop</span></code> - Deploy the project source in “Development Mode”</a><a class="headerlink" href="#develop-deploy-the-project-source-in-development-mode" title="Permalink to this headline">¶</a></h4>
<p>This command allows you to deploy your project’s source for use in one or more
“staging areas” where it will be available for importing.  This deployment is
done in such a way that changes to the project source are immediately available
in the staging area(s), without needing to run a build or install step after
each change.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">develop</span></code> command works by creating an <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> file (named for the
project) in the given staging area.  If the staging area is Python’s
<code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory, it also updates an <code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> file so
that the project is on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> by default for all programs run using that
Python installation.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">develop</span></code> command also installs wrapper scripts in the staging area (or
a separate directory, as specified) that will ensure the project’s dependencies
are available on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> before running the project’s source scripts.
And, it ensures that any missing project dependencies are available in the
staging area, by downloading and installing them if necessary.</p>
<p>Last, but not least, the <code class="docutils literal notranslate"><span class="pre">develop</span></code> command invokes the <code class="docutils literal notranslate"><span class="pre">build_ext</span> <span class="pre">-i</span></code>
command to ensure any C extensions in the project have been built and are
up-to-date, and the <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command to ensure the project’s metadata is
updated (so that the runtime and wrappers know what the project’s dependencies
are).  If you make any changes to the project’s setup script or C extensions,
you should rerun the <code class="docutils literal notranslate"><span class="pre">develop</span></code> command against all relevant staging areas to
keep the project’s scripts, metadata and extensions up-to-date.  Most other
kinds of changes to your project should not require any build operations or
rerunning <code class="docutils literal notranslate"><span class="pre">develop</span></code>, but keep in mind that even minor changes to the setup
script (e.g. changing an entry point definition) require you to re-run the
<code class="docutils literal notranslate"><span class="pre">develop</span></code> or <code class="docutils literal notranslate"><span class="pre">test</span></code> commands to keep the distribution updated.</p>
<p>Here are some of the options that the <code class="docutils literal notranslate"><span class="pre">develop</span></code> command accepts.  Note that
they affect the project’s dependencies as well as the project itself, so if you
have dependencies that need to be installed and you use <code class="docutils literal notranslate"><span class="pre">--exclude-scripts</span></code>
(for example), the dependencies’ scripts will not be installed either!  For
this reason, you may want to use pip to install the project’s dependencies
before using the <code class="docutils literal notranslate"><span class="pre">develop</span></code> command, if you need finer control over the
installation options for dependencies.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">--uninstall,</span> <span class="pre">-u</span></code></dt>
<dd><p class="first">Un-deploy the current project.  You may use the <code class="docutils literal notranslate"><span class="pre">--install-dir</span></code> or <code class="docutils literal notranslate"><span class="pre">-d</span></code>
option to designate the staging area.  The created <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> file will
be removed, if present and it is still pointing to the project directory.
The project directory will be removed from <code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> if the
staging area is Python’s <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory.</p>
<p class="last">Note that this option currently does <em>not</em> uninstall script wrappers!  You
must uninstall them yourself, or overwrite them by using pip to install a
different version of the package.  You can also avoid installing script
wrappers in the first place, if you use the <code class="docutils literal notranslate"><span class="pre">--exclude-scripts</span></code> (aka
<code class="docutils literal notranslate"><span class="pre">-x</span></code>) option when you run <code class="docutils literal notranslate"><span class="pre">develop</span></code> to deploy the project.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--multi-version,</span> <span class="pre">-m</span></code></dt>
<dd><p class="first">“Multi-version” mode. Specifying this option prevents <code class="docutils literal notranslate"><span class="pre">develop</span></code> from
adding an <code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> entry for the project(s) being deployed, and
if an entry for any version of a project already exists, the entry will be
removed upon successful deployment.  In multi-version mode, no specific
version of the package is available for importing, unless you use
<code class="docutils literal notranslate"><span class="pre">pkg_resources.require()</span></code> to put it on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, or you are running
a wrapper script generated by <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>.  (In which case the wrapper
script calls <code class="docutils literal notranslate"><span class="pre">require()</span></code> for you.)</p>
<p class="last">Note that if you install to a directory other than <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>,
this option is automatically in effect, because <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files can only be
used in <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> (at least in Python 2.3 and 2.4). So, if you use
the <code class="docutils literal notranslate"><span class="pre">--install-dir</span></code> or <code class="docutils literal notranslate"><span class="pre">-d</span></code> option (or they are set via configuration
file(s)) your project and its dependencies will be deployed in multi-
version mode.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--install-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></code></dt>
<dd>Set the installation directory (staging area).  If this option is not
directly specified on the command line or in a distutils configuration
file, the distutils default installation location is used.  Normally, this
will be the <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory, but if you are using distutils
configuration files, setting things like <code class="docutils literal notranslate"><span class="pre">prefix</span></code> or <code class="docutils literal notranslate"><span class="pre">install_lib</span></code>,
then those settings are taken into account when computing the default
staging area.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--script-dir=DIR,</span> <span class="pre">-s</span> <span class="pre">DIR</span></code></dt>
<dd>Set the script installation directory.  If you don’t supply this option
(via the command line or a configuration file), but you <em>have</em> supplied
an <code class="docutils literal notranslate"><span class="pre">--install-dir</span></code> (via command line or config file), then this option
defaults to the same directory, so that the scripts will be able to find
their associated package installation.  Otherwise, this setting defaults
to the location where the distutils would normally install scripts, taking
any distutils configuration file settings into account.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--exclude-scripts,</span> <span class="pre">-x</span></code></dt>
<dd>Don’t deploy script wrappers.  This is useful if you don’t want to disturb
existing versions of the scripts in the staging area.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--always-copy,</span> <span class="pre">-a</span></code></dt>
<dd>Copy all needed distributions to the staging area, even if they
are already present in another directory on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.  By default, if
a requirement can be met using a distribution that is already available in
a directory on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, it will not be copied to the staging area.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--egg-path=DIR</span></code></dt>
<dd>Force the generated <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> file to use a specified relative path
to the source directory.  This can be useful in circumstances where your
installation directory is being shared by code running under multiple
platforms (e.g. Mac and Windows) which have different absolute locations
for the code under development, but the same <em>relative</em> locations with
respect to the installation directory.  If you use this option when
installing, you must supply the same relative path when uninstalling.</dd>
</dl>
<p>In addition to the above options, the <code class="docutils literal notranslate"><span class="pre">develop</span></code> command also accepts all of
the same options accepted by <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>.  If you’ve configured any
<code class="docutils literal notranslate"><span class="pre">easy_install</span></code> settings in your <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> (or other distutils config
files), the <code class="docutils literal notranslate"><span class="pre">develop</span></code> command will use them as defaults, unless you override
them in a <code class="docutils literal notranslate"><span class="pre">[develop]</span></code> section or on the command line.</p>
</div>
<div class="section" id="egg-info-create-egg-metadata-and-set-build-tags">
<span id="egg-info"></span><h4><a class="toc-backref" href="#id37"><code class="docutils literal notranslate"><span class="pre">egg_info</span></code> - Create egg metadata and set build tags</a><a class="headerlink" href="#egg-info-create-egg-metadata-and-set-build-tags" title="Permalink to this headline">¶</a></h4>
<p>This command performs two operations: it updates a project’s <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code>
metadata directory (used by the <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code>, <code class="docutils literal notranslate"><span class="pre">develop</span></code>, and <code class="docutils literal notranslate"><span class="pre">test</span></code>
commands), and it allows you to temporarily change a project’s version string,
to support “daily builds” or “snapshot” releases.  It is run automatically by
the <code class="docutils literal notranslate"><span class="pre">sdist</span></code>, <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code>, <code class="docutils literal notranslate"><span class="pre">develop</span></code>, and <code class="docutils literal notranslate"><span class="pre">test</span></code> commands in order to
update the project’s metadata, but you can also specify it explicitly in order
to temporarily change the project’s version string while executing other
commands.  (It also generates the <code class="docutils literal notranslate"><span class="pre">.egg-info/SOURCES.txt</span></code> manifest file, which
is used when you are building source distributions.)</p>
<p>In addition to writing the core egg metadata defined by <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> and
required by <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>, this command can be extended to write other
metadata files as well, by defining entry points in the <code class="docutils literal notranslate"><span class="pre">egg_info.writers</span></code>
group.  See the section on <a class="reference internal" href="#adding-new-egg-info-files">Adding new EGG-INFO Files</a> below for more details.
Note that using additional metadata writers may require you to include a
<code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> argument to <code class="docutils literal notranslate"><span class="pre">setup()</span></code> in order to ensure that the desired
writers are available on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.</p>
<div class="section" id="release-tagging-options">
<h5><a class="toc-backref" href="#id38">Release Tagging Options</a><a class="headerlink" href="#release-tagging-options" title="Permalink to this headline">¶</a></h5>
<p>The following options can be used to modify the project’s version string for
all remaining commands on the setup command line.  The options are processed
in the order shown, so if you use more than one, the requested tags will be
added in the following order:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">--tag-build=NAME,</span> <span class="pre">-b</span> <span class="pre">NAME</span></code></dt>
<dd><p class="first">Append NAME to the project’s version string.  Due to the way setuptools
processes “pre-release” version suffixes beginning with the letters “a”
through “e” (like “alpha”, “beta”, and “candidate”), you will usually want
to use a tag like “.build” or “.dev”, as this will cause the version number
to be considered <em>lower</em> than the project’s default version.  (If you
want to make the version number <em>higher</em> than the default version, you can
always leave off –tag-build and then use one or both of the following
options.)</p>
<p class="last">If you have a default build tag set in your <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>, you can suppress
it on the command line using <code class="docutils literal notranslate"><span class="pre">-b</span> <span class="pre">&quot;&quot;</span></code> or <code class="docutils literal notranslate"><span class="pre">--tag-build=&quot;&quot;</span></code> as an argument
to the <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--tag-date,</span> <span class="pre">-d</span></code></dt>
<dd>Add a date stamp of the form “-YYYYMMDD” (e.g. “-20050528”) to the
project’s version number.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--no-date,</span> <span class="pre">-D</span></code></dt>
<dd>Don’t include a date stamp in the version number.  This option is included
so you can override a default setting in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>.</dd>
</dl>
<p>(Note: Because these options modify the version number used for source and
binary distributions of your project, you should first make sure that you know
how the resulting version numbers will be interpreted by automated tools
like pip.  See the section above on <a class="reference internal" href="#specifying-your-project-s-version">Specifying Your Project’s Version</a> for an
explanation of pre- and post-release tags, as well as tips on how to choose and
verify a versioning scheme for your project.)</p>
<p>For advanced uses, there is one other option that can be set, to change the
location of the project’s <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> directory.  Commands that need to find
the project’s source directory or metadata should get it from this setting:</p>
</div>
<div class="section" id="other-egg-info-options">
<h5><a class="toc-backref" href="#id39">Other <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> Options</a><a class="headerlink" href="#other-egg-info-options" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">--egg-base=SOURCEDIR,</span> <span class="pre">-e</span> <span class="pre">SOURCEDIR</span></code></dt>
<dd>Specify the directory that should contain the .egg-info directory.  This
should normally be the root of your project’s source tree (which is not
necessarily the same as your project directory; some projects use a <code class="docutils literal notranslate"><span class="pre">src</span></code>
or <code class="docutils literal notranslate"><span class="pre">lib</span></code> subdirectory as the source root).  You should not normally need
to specify this directory, as it is normally determined from the
<code class="docutils literal notranslate"><span class="pre">package_dir</span></code> argument to the <code class="docutils literal notranslate"><span class="pre">setup()</span></code> function, if any.  If there is
no <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> set, this option defaults to the current directory.</dd>
</dl>
</div>
<div class="section" id="egg-info-examples">
<h5><a class="toc-backref" href="#id40"><code class="docutils literal notranslate"><span class="pre">egg_info</span></code> Examples</a><a class="headerlink" href="#egg-info-examples" title="Permalink to this headline">¶</a></h5>
<p>Creating a dated “nightly build” snapshot egg:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">egg_info</span> <span class="o">--</span><span class="n">tag</span><span class="o">-</span><span class="n">date</span> <span class="o">--</span><span class="n">tag</span><span class="o">-</span><span class="n">build</span><span class="o">=</span><span class="n">DEV</span> <span class="n">bdist_egg</span>
</pre></div>
</div>
<p>Creating a release with no version tags, even if some default tags are
specified in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">egg_info</span> <span class="o">-</span><span class="n">RDb</span> <span class="s2">&quot;&quot;</span> <span class="n">sdist</span> <span class="n">bdist_egg</span>
</pre></div>
</div>
<p>(Notice that <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> must always appear on the command line <em>before</em> any
commands that you want the version changes to apply to.)</p>
</div>
</div>
<div class="section" id="rotate-delete-outdated-distribution-files">
<span id="rotate"></span><h4><a class="toc-backref" href="#id41"><code class="docutils literal notranslate"><span class="pre">rotate</span></code> - Delete outdated distribution files</a><a class="headerlink" href="#rotate-delete-outdated-distribution-files" title="Permalink to this headline">¶</a></h4>
<p>As you develop new versions of your project, your distribution (<code class="docutils literal notranslate"><span class="pre">dist</span></code>)
directory will gradually fill up with older source and/or binary distribution
files.  The <code class="docutils literal notranslate"><span class="pre">rotate</span></code> command lets you automatically clean these up, keeping
only the N most-recently modified files matching a given pattern.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">--match=PATTERNLIST,</span> <span class="pre">-m</span> <span class="pre">PATTERNLIST</span></code></dt>
<dd>Comma-separated list of glob patterns to match.  This option is <em>required</em>.
The project name and <code class="docutils literal notranslate"><span class="pre">-*</span></code> is prepended to the supplied patterns, in order
to match only distributions belonging to the current project (in case you
have a shared distribution directory for multiple projects).  Typically,
you will use a glob pattern like <code class="docutils literal notranslate"><span class="pre">.zip</span></code> or <code class="docutils literal notranslate"><span class="pre">.egg</span></code> to match files of
the specified type.  Note that each supplied pattern is treated as a
distinct group of files for purposes of selecting files to delete.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--keep=COUNT,</span> <span class="pre">-k</span> <span class="pre">COUNT</span></code></dt>
<dd>Number of matching distributions to keep.  For each group of files
identified by a pattern specified with the <code class="docutils literal notranslate"><span class="pre">--match</span></code> option, delete all
but the COUNT most-recently-modified files in that group.  This option is
<em>required</em>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--dist-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></code></dt>
<dd>Directory where the distributions are.  This defaults to the value of the
<code class="docutils literal notranslate"><span class="pre">bdist</span></code> command’s <code class="docutils literal notranslate"><span class="pre">--dist-dir</span></code> option, which will usually be the
project’s <code class="docutils literal notranslate"><span class="pre">dist</span></code> subdirectory.</dd>
</dl>
<p><strong>Example 1</strong>: Delete all .tar.gz files from the distribution directory, except
for the 3 most recently modified ones:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">rotate</span> <span class="o">--</span><span class="n">match</span><span class="o">=.</span><span class="n">tar</span><span class="o">.</span><span class="n">gz</span> <span class="o">--</span><span class="n">keep</span><span class="o">=</span><span class="mi">3</span>
</pre></div>
</div>
<p><strong>Example 2</strong>: Delete all Python 2.3 or Python 2.4 eggs from the distribution
directory, except the most recently modified one for each Python version:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">rotate</span> <span class="o">--</span><span class="n">match</span><span class="o">=-</span><span class="n">py2</span><span class="o">.</span><span class="mi">3</span><span class="o">*.</span><span class="n">egg</span><span class="p">,</span><span class="o">-</span><span class="n">py2</span><span class="o">.</span><span class="mi">4</span><span class="o">*.</span><span class="n">egg</span> <span class="o">--</span><span class="n">keep</span><span class="o">=</span><span class="mi">1</span>
</pre></div>
</div>
</div>
<div class="section" id="saveopts-save-used-options-to-a-configuration-file">
<span id="saveopts"></span><h4><a class="toc-backref" href="#id42"><code class="docutils literal notranslate"><span class="pre">saveopts</span></code> - Save used options to a configuration file</a><a class="headerlink" href="#saveopts-save-used-options-to-a-configuration-file" title="Permalink to this headline">¶</a></h4>
<p>Finding and editing <code class="docutils literal notranslate"><span class="pre">distutils</span></code> configuration files can be a pain, especially
since you also have to translate the configuration options from command-line
form to the proper configuration file format.  You can avoid these hassles by
using the <code class="docutils literal notranslate"><span class="pre">saveopts</span></code> command.  Just add it to the command line to save the
options you used.  For example, this command builds the project using
the <code class="docutils literal notranslate"><span class="pre">mingw32</span></code> C compiler, then saves the –compiler setting as the default
for future builds (even those run implicitly by the <code class="docutils literal notranslate"><span class="pre">install</span></code> command):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">build</span> <span class="o">--</span><span class="n">compiler</span><span class="o">=</span><span class="n">mingw32</span> <span class="n">saveopts</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">saveopts</span></code> command saves all options for every command specified on the
command line to the project’s local <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> file, unless you use one of
the <a class="reference internal" href="#configuration-file-options">configuration file options</a> to change where the options are saved.  For
example, this command does the same as above, but saves the compiler setting
to the site-wide (global) distutils configuration:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">build</span> <span class="o">--</span><span class="n">compiler</span><span class="o">=</span><span class="n">mingw32</span> <span class="n">saveopts</span> <span class="o">-</span><span class="n">g</span>
</pre></div>
</div>
<p>Note that it doesn’t matter where you place the <code class="docutils literal notranslate"><span class="pre">saveopts</span></code> command on the
command line; it will still save all the options specified for all commands.
For example, this is another valid way to spell the last example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">saveopts</span> <span class="o">-</span><span class="n">g</span> <span class="n">build</span> <span class="o">--</span><span class="n">compiler</span><span class="o">=</span><span class="n">mingw32</span>
</pre></div>
</div>
<p>Note, however, that all of the commands specified are always run, regardless of
where <code class="docutils literal notranslate"><span class="pre">saveopts</span></code> is placed on the command line.</p>
<div class="section" id="configuration-file-options">
<h5><a class="toc-backref" href="#id43">Configuration File Options</a><a class="headerlink" href="#configuration-file-options" title="Permalink to this headline">¶</a></h5>
<p>Normally, settings such as options and aliases are saved to the project’s
local <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> file.  But you can override this and save them to the
global or per-user configuration files, or to a manually-specified filename.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">--global-config,</span> <span class="pre">-g</span></code></dt>
<dd>Save settings to the global <code class="docutils literal notranslate"><span class="pre">distutils.cfg</span></code> file inside the <code class="docutils literal notranslate"><span class="pre">distutils</span></code>
package directory.  You must have write access to that directory to use
this option.  You also can’t combine this option with <code class="docutils literal notranslate"><span class="pre">-u</span></code> or <code class="docutils literal notranslate"><span class="pre">-f</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--user-config,</span> <span class="pre">-u</span></code></dt>
<dd>Save settings to the current user’s <code class="docutils literal notranslate"><span class="pre">~/.pydistutils.cfg</span></code> (POSIX) or
<code class="docutils literal notranslate"><span class="pre">$HOME/pydistutils.cfg</span></code> (Windows) file.  You can’t combine this option
with <code class="docutils literal notranslate"><span class="pre">-g</span></code> or <code class="docutils literal notranslate"><span class="pre">-f</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--filename=FILENAME,</span> <span class="pre">-f</span> <span class="pre">FILENAME</span></code></dt>
<dd>Save settings to the specified configuration file to use.  You can’t
combine this option with <code class="docutils literal notranslate"><span class="pre">-g</span></code> or <code class="docutils literal notranslate"><span class="pre">-u</span></code>.  Note that if you specify a
non-standard filename, the <code class="docutils literal notranslate"><span class="pre">distutils</span></code> and <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> will not
use the file’s contents.  This option is mainly included for use in
testing.</dd>
</dl>
<p>These options are used by other <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> commands that modify
configuration files, such as the <a class="reference internal" href="#alias">alias</a> and <a class="reference internal" href="#setopt">setopt</a> commands.</p>
</div>
</div>
<div class="section" id="setopt-set-a-distutils-or-setuptools-option-in-a-config-file">
<span id="setopt"></span><h4><a class="toc-backref" href="#id44"><code class="docutils literal notranslate"><span class="pre">setopt</span></code> - Set a distutils or setuptools option in a config file</a><a class="headerlink" href="#setopt-set-a-distutils-or-setuptools-option-in-a-config-file" title="Permalink to this headline">¶</a></h4>
<p>This command is mainly for use by scripts, but it can also be used as a quick
and dirty way to change a distutils configuration option without having to
remember what file the options are in and then open an editor.</p>
<p><strong>Example 1</strong>.  Set the default C compiler to <code class="docutils literal notranslate"><span class="pre">mingw32</span></code> (using long option
names):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">setopt</span> <span class="o">--</span><span class="n">command</span><span class="o">=</span><span class="n">build</span> <span class="o">--</span><span class="n">option</span><span class="o">=</span><span class="n">compiler</span> <span class="o">--</span><span class="nb">set</span><span class="o">-</span><span class="n">value</span><span class="o">=</span><span class="n">mingw32</span>
</pre></div>
</div>
<p><strong>Example 2</strong>.  Remove any setting for the distutils default package
installation directory (short option names):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">setopt</span> <span class="o">-</span><span class="n">c</span> <span class="n">install</span> <span class="o">-</span><span class="n">o</span> <span class="n">install_lib</span> <span class="o">-</span><span class="n">r</span>
</pre></div>
</div>
<p>Options for the <code class="docutils literal notranslate"><span class="pre">setopt</span></code> command:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">--command=COMMAND,</span> <span class="pre">-c</span> <span class="pre">COMMAND</span></code></dt>
<dd>Command to set the option for.  This option is required.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--option=OPTION,</span> <span class="pre">-o</span> <span class="pre">OPTION</span></code></dt>
<dd>The name of the option to set.  This option is required.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--set-value=VALUE,</span> <span class="pre">-s</span> <span class="pre">VALUE</span></code></dt>
<dd>The value to set the option to.  Not needed if <code class="docutils literal notranslate"><span class="pre">-r</span></code> or <code class="docutils literal notranslate"><span class="pre">--remove</span></code> is
set.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--remove,</span> <span class="pre">-r</span></code></dt>
<dd>Remove (unset) the option, instead of setting it.</dd>
</dl>
<p>In addition to the above options, you may use any of the <a class="reference internal" href="#configuration-file-options">configuration file
options</a> (listed under the <a class="reference internal" href="#saveopts">saveopts</a> command, above) to determine which
distutils configuration file the option will be added to (or removed from).</p>
</div>
<div class="section" id="test-build-package-and-run-a-unittest-suite">
<span id="test"></span><h4><a class="toc-backref" href="#id45"><code class="docutils literal notranslate"><span class="pre">test</span></code> - Build package and run a unittest suite</a><a class="headerlink" href="#test-build-package-and-run-a-unittest-suite" title="Permalink to this headline">¶</a></h4>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last"><code class="docutils literal notranslate"><span class="pre">test</span></code> is deprecated and will be removed in a future version. Users
looking for a generic test entry point independent of test runner are
encouraged to use <a class="reference external" href="https://tox.readthedocs.io">tox</a>.</p>
</div>
<p>When doing test-driven development, or running automated builds that need
testing before they are deployed for downloading or use, it’s often useful
to be able to run a project’s unit tests without actually deploying the project
anywhere, even using the <code class="docutils literal notranslate"><span class="pre">develop</span></code> command.  The <code class="docutils literal notranslate"><span class="pre">test</span></code> command runs a
project’s unit tests without actually deploying it, by temporarily putting the
project’s source on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, after first running <code class="docutils literal notranslate"><span class="pre">build_ext</span> <span class="pre">-i</span></code> and
<code class="docutils literal notranslate"><span class="pre">egg_info</span></code> to ensure that any C extensions and project metadata are
up-to-date.</p>
<p>To use this command, your project’s tests must be wrapped in a <code class="docutils literal notranslate"><span class="pre">unittest</span></code>
test suite by either a function, a <code class="docutils literal notranslate"><span class="pre">TestCase</span></code> class or method, or a module
or package containing <code class="docutils literal notranslate"><span class="pre">TestCase</span></code> classes.  If the named suite is a module,
and the module has an <code class="docutils literal notranslate"><span class="pre">additional_tests()</span></code> function, it is called and the
result (which must be a <code class="docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code>) is added to the tests to be
run.  If the named suite is a package, any submodules and subpackages are
recursively added to the overall test suite.  (Note: if your project specifies
a <code class="docutils literal notranslate"><span class="pre">test_loader</span></code>, the rules for processing the chosen <code class="docutils literal notranslate"><span class="pre">test_suite</span></code> may
differ; see the <a class="reference internal" href="#test-loader">test_loader</a> documentation for more details.)</p>
<p>Note that many test systems including <code class="docutils literal notranslate"><span class="pre">doctest</span></code> support wrapping their
non-<code class="docutils literal notranslate"><span class="pre">unittest</span></code> tests in <code class="docutils literal notranslate"><span class="pre">TestSuite</span></code> objects.  So, if you are using a test
package that does not support this, we suggest you encourage its developers to
implement test suite support, as this is a convenient and standard way to
aggregate a collection of tests to be run under a common test harness.</p>
<p>By default, tests will be run in the “verbose” mode of the <code class="docutils literal notranslate"><span class="pre">unittest</span></code>
package’s text test runner, but you can get the “quiet” mode (just dots) if
you supply the <code class="docutils literal notranslate"><span class="pre">-q</span></code> or <code class="docutils literal notranslate"><span class="pre">--quiet</span></code> option, either as a global option to
the setup script (e.g. <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">-q</span> <span class="pre">test</span></code>) or as an option for the <code class="docutils literal notranslate"><span class="pre">test</span></code>
command itself (e.g. <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">test</span> <span class="pre">-q</span></code>).  There is one other option
available:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">--test-suite=NAME,</span> <span class="pre">-s</span> <span class="pre">NAME</span></code></dt>
<dd><p class="first">Specify the test suite (or module, class, or method) to be run
(e.g. <code class="docutils literal notranslate"><span class="pre">some_module.test_suite</span></code>).  The default for this option can be
set by giving a <code class="docutils literal notranslate"><span class="pre">test_suite</span></code> argument to the <code class="docutils literal notranslate"><span class="pre">setup()</span></code> function, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">test_suite</span><span class="o">=</span><span class="s2">&quot;my_package.tests.test_all&quot;</span>
<span class="p">)</span>
</pre></div>
</div>
<p class="last">If you did not set a <code class="docutils literal notranslate"><span class="pre">test_suite</span></code> in your <code class="docutils literal notranslate"><span class="pre">setup()</span></code> call, and do not
provide a <code class="docutils literal notranslate"><span class="pre">--test-suite</span></code> option, an error will occur.</p>
</dd>
</dl>
<p>New in 41.5.0: Deprecated the test command.</p>
</div>
<div class="section" id="upload-upload-source-and-or-egg-distributions-to-pypi">
<span id="upload"></span><h4><a class="toc-backref" href="#id46"><code class="docutils literal notranslate"><span class="pre">upload</span></code> - Upload source and/or egg distributions to PyPI</a><a class="headerlink" href="#upload-upload-source-and-or-egg-distributions-to-pypi" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">upload</span></code> command was deprecated in version 40.0 and removed in version
42.0. Use <a class="reference external" href="https://pypi.org/p/twine">twine</a> instead.</p>
<p>For  more information on the current best practices in uploading your packages
to PyPI, see the Python Packaging User Guide’s “Packaging Python Projects”
tutorial specifically the section on <a class="reference external" href="https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives">uploading the distribution archives</a>.</p>
</div>
</div>
<div class="section" id="configuring-setup-using-setup-cfg-files">
<h3><a class="toc-backref" href="#id47">Configuring setup() using setup.cfg files</a><a class="headerlink" href="#configuring-setup-using-setup-cfg-files" title="Permalink to this headline">¶</a></h3>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">New in 30.3.0 (8 Dec 2016).</p>
</div>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">A <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> file containing a <code class="docutils literal notranslate"><span class="pre">setup()</span></code> function call is still
required even if your configuration resides in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>.</p>
</div>
<p><code class="docutils literal notranslate"><span class="pre">Setuptools</span></code> allows using configuration files (usually <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>)
to define a package’s metadata and other options that are normally supplied
to the <code class="docutils literal notranslate"><span class="pre">setup()</span></code> function (declarative config).</p>
<p>This approach not only allows automation scenarios but also reduces
boilerplate code in some cases.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>This implementation has limited compatibility with the distutils2-like
<code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> sections used by the <code class="docutils literal notranslate"><span class="pre">pbr</span></code> and <code class="docutils literal notranslate"><span class="pre">d2to1</span></code> packages.</p>
<p class="last">Namely: only metadata-related keys from <code class="docutils literal notranslate"><span class="pre">metadata</span></code> section are supported
(except for <code class="docutils literal notranslate"><span class="pre">description-file</span></code>); keys from <code class="docutils literal notranslate"><span class="pre">files</span></code>, <code class="docutils literal notranslate"><span class="pre">entry_points</span></code>
and <code class="docutils literal notranslate"><span class="pre">backwards_compat</span></code> are not supported.</p>
</div>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[metadata]</span>
<span class="na">name</span> <span class="o">=</span> <span class="s">my_package</span>
<span class="na">version</span> <span class="o">=</span> <span class="s">attr: src.VERSION</span>
<span class="na">description</span> <span class="o">=</span> <span class="s">My package description</span>
<span class="na">long_description</span> <span class="o">=</span> <span class="s">file: README.rst, CHANGELOG.rst, LICENSE.rst</span>
<span class="na">keywords</span> <span class="o">=</span> <span class="s">one, two</span>
<span class="na">license</span> <span class="o">=</span> <span class="s">BSD 3-Clause License</span>
<span class="na">classifiers</span> <span class="o">=</span><span class="s"></span>
<span class="s">    Framework :: Django</span>
<span class="s">    License :: OSI Approved :: BSD License</span>
<span class="s">    Programming Language :: Python :: 3</span>
<span class="s">    Programming Language :: Python :: 3.5</span>

<span class="k">[options]</span>
<span class="na">zip_safe</span> <span class="o">=</span> <span class="s">False</span>
<span class="na">include_package_data</span> <span class="o">=</span> <span class="s">True</span>
<span class="na">packages</span> <span class="o">=</span> <span class="s">find:</span>
<span class="na">scripts</span> <span class="o">=</span><span class="s"></span>
<span class="s">  bin/first.py</span>
<span class="s">  bin/second.py</span>
<span class="na">install_requires</span> <span class="o">=</span><span class="s"></span>
<span class="s">  requests</span>
<span class="s">  importlib; python_version == &quot;2.6&quot;</span>

<span class="k">[options.package_data]</span>
<span class="na">*</span> <span class="o">=</span> <span class="s">*.txt, *.rst</span>
<span class="na">hello</span> <span class="o">=</span> <span class="s">*.msg</span>

<span class="k">[options.extras_require]</span>
<span class="na">pdf</span> <span class="o">=</span> <span class="s">ReportLab&gt;=1.2; RXP</span>
<span class="na">rest</span> <span class="o">=</span> <span class="s">docutils&gt;=0.3; pack ==1.1, ==1.3</span>

<span class="k">[options.packages.find]</span>
<span class="na">exclude</span> <span class="o">=</span><span class="s"></span>
<span class="s">    src.subpackage1</span>
<span class="s">    src.subpackage2</span>

<span class="k">[options.data_files]</span>
<span class="na">/etc/my_package</span> <span class="o">=</span><span class="s"></span>
<span class="s">    site.d/00_default.conf</span>
<span class="s">    host.d/00_default.conf</span>
<span class="na">data</span> <span class="o">=</span> <span class="s">data/img/logo.png, data/svg/icon.svg</span>
</pre></div>
</div>
<p>Metadata and options are set in the config sections of the same name.</p>
<ul>
<li><p class="first">Keys are the same as the keyword arguments one provides to the <code class="docutils literal notranslate"><span class="pre">setup()</span></code>
function.</p>
</li>
<li><p class="first">Complex values can be written comma-separated or placed one per line
in <em>dangling</em> config values. The following are equivalent:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[metadata]</span>
<span class="na">keywords</span> <span class="o">=</span> <span class="s">one, two</span>

<span class="k">[metadata]</span>
<span class="na">keywords</span> <span class="o">=</span><span class="s"></span>
<span class="s">  one</span>
<span class="s">  two</span>
</pre></div>
</div>
</li>
<li><p class="first">In some cases, complex values can be provided in dedicated subsections for
clarity.</p>
</li>
<li><p class="first">Some keys allow <code class="docutils literal notranslate"><span class="pre">file:</span></code>, <code class="docutils literal notranslate"><span class="pre">attr:</span></code>, and <code class="docutils literal notranslate"><span class="pre">find:</span></code> and <code class="docutils literal notranslate"><span class="pre">find_namespace:</span></code> directives in
order to cover common usecases.</p>
</li>
<li><p class="first">Unknown keys are ignored.</p>
</li>
</ul>
<div class="section" id="using-a-src-layout">
<h4><a class="toc-backref" href="#id48">Using a <code class="docutils literal notranslate"><span class="pre">src/</span></code> layout</a><a class="headerlink" href="#using-a-src-layout" title="Permalink to this headline">¶</a></h4>
<p>One commonly used package configuration has all the module source code in a
subdirectory (often called the <code class="docutils literal notranslate"><span class="pre">src/</span></code> layout), like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>├── src
│   └── mypackage
│       ├── __init__.py
│       └── mod1.py
├── setup.py
└── setup.cfg
</pre></div>
</div>
<p>You can set up your <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> to automatically find all your packages in
the subdirectory like this:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example contains just the necessary options for a src-layout, set up</span>
<span class="c1"># the rest of the file as described above.</span>

<span class="k">[options]</span>
<span class="na">package_dir</span><span class="o">=</span><span class="s"></span>
<span class="s">    =src</span>
<span class="na">packages</span><span class="o">=</span><span class="s">find:</span>

<span class="k">[options.packages.find]</span>
<span class="na">where</span><span class="o">=</span><span class="s">src</span>
</pre></div>
</div>
</div>
<div class="section" id="specifying-values">
<h4><a class="toc-backref" href="#id49">Specifying values</a><a class="headerlink" href="#specifying-values" title="Permalink to this headline">¶</a></h4>
<p>Some values are treated as simple strings, some allow more logic.</p>
<p>Type names used below:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">str</span></code> - simple string</li>
<li><code class="docutils literal notranslate"><span class="pre">list-comma</span></code> - dangling list or string of comma-separated values</li>
<li><code class="docutils literal notranslate"><span class="pre">list-semi</span></code> - dangling list or string of semicolon-separated values</li>
<li><code class="docutils literal notranslate"><span class="pre">bool</span></code> - <code class="docutils literal notranslate"><span class="pre">True</span></code> is 1, yes, true</li>
<li><code class="docutils literal notranslate"><span class="pre">dict</span></code> - list-comma where keys are separated from values by <code class="docutils literal notranslate"><span class="pre">=</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">section</span></code> - values are read from a dedicated (sub)section</li>
</ul>
<p>Special directives:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">attr:</span></code> - Value is read from a module attribute.  <code class="docutils literal notranslate"><span class="pre">attr:</span></code> supports
callables and iterables; unsupported types are cast using <code class="docutils literal notranslate"><span class="pre">str()</span></code>.</li>
<li><code class="docutils literal notranslate"><span class="pre">file:</span></code> - Value is read from a list of files and then concatenated</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <code class="docutils literal notranslate"><span class="pre">file:</span></code> directive is sandboxed and won’t reach anything outside
the directory containing <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>.</p>
</div>
<div class="section" id="metadata">
<h5><a class="toc-backref" href="#id50">Metadata</a><a class="headerlink" href="#metadata" title="Permalink to this headline">¶</a></h5>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The aliases given below are supported for compatibility reasons,
but their use is not advised.</p>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="36%" />
<col width="20%" />
<col width="20%" />
<col width="18%" />
<col width="6%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Key</th>
<th class="head">Aliases</th>
<th class="head">Type</th>
<th class="head">Minimum Version</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>name</td>
<td>&#160;</td>
<td>str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>version</td>
<td>&#160;</td>
<td>attr:, file:, str</td>
<td>39.2.0</td>
<td><ol class="first last arabic simple">
<li></li>
</ol>
</td>
</tr>
<tr class="row-even"><td>url</td>
<td>home-page</td>
<td>str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>download_url</td>
<td>download-url</td>
<td>str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>project_urls</td>
<td>&#160;</td>
<td>dict</td>
<td>38.3.0</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>author</td>
<td>&#160;</td>
<td>str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>author_email</td>
<td>author-email</td>
<td>str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>maintainer</td>
<td>&#160;</td>
<td>str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>maintainer_email</td>
<td>maintainer-email</td>
<td>str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>classifiers</td>
<td>classifier</td>
<td>file:, list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>license</td>
<td>&#160;</td>
<td>str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>license_file</td>
<td>&#160;</td>
<td>str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>license_files</td>
<td>&#160;</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>description</td>
<td>summary</td>
<td>file:, str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>long_description</td>
<td>long-description</td>
<td>file:, str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>long_description_content_type</td>
<td>&#160;</td>
<td>str</td>
<td>38.6.0</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>keywords</td>
<td>&#160;</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>platforms</td>
<td>platform</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>provides</td>
<td>&#160;</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>requires</td>
<td>&#160;</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>obsoletes</td>
<td>&#160;</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">A version loaded using the <code class="docutils literal notranslate"><span class="pre">file:</span></code> directive must comply with PEP 440.
It is easy to accidentally put something other than a valid version
string in such a file, so validation is stricter in this case.</p>
</div>
<p>Notes:
1. The <cite>version</cite> file attribute has only been supported since 39.2.0.</p>
</div>
<div class="section" id="options">
<h5><a class="toc-backref" href="#id51">Options</a><a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h5>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="45%" />
<col width="19%" />
<col width="6%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Key</th>
<th class="head">Type</th>
<th class="head">Minimum Version</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>zip_safe</td>
<td>bool</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>setup_requires</td>
<td>list-semi</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>install_requires</td>
<td>list-semi</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>extras_require</td>
<td>section</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>python_requires</td>
<td>str</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>entry_points</td>
<td>file:, section</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>use_2to3</td>
<td>bool</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>use_2to3_fixers</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>use_2to3_exclude_fixers</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>convert_2to3_doctests</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>scripts</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>eager_resources</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>dependency_links</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>tests_require</td>
<td>list-semi</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>include_package_data</td>
<td>bool</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>packages</td>
<td>find:, find_namespace:, list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>package_dir</td>
<td>dict</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>package_data</td>
<td>section</td>
<td>&#160;</td>
<td><ol class="first last arabic simple">
<li></li>
</ol>
</td>
</tr>
<tr class="row-even"><td>exclude_package_data</td>
<td>section</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>namespace_packages</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-even"><td>py_modules</td>
<td>list-comma</td>
<td>&#160;</td>
<td>&#160;</td>
</tr>
<tr class="row-odd"><td>data_files</td>
<td>dict</td>
<td>40.6.0</td>
<td>&#160;</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p><strong>packages</strong> - The <code class="docutils literal notranslate"><span class="pre">find:</span></code> and <code class="docutils literal notranslate"><span class="pre">find_namespace:</span></code> directive can be further configured
in a dedicated subsection <code class="docutils literal notranslate"><span class="pre">options.packages.find</span></code>. This subsection
accepts the same keys as the <cite>setuptools.find_packages</cite> and the
<cite>setuptools.find_namespace_packages</cite> function:
<code class="docutils literal notranslate"><span class="pre">where</span></code>, <code class="docutils literal notranslate"><span class="pre">include</span></code>, and <code class="docutils literal notranslate"><span class="pre">exclude</span></code>.</p>
<p class="last"><strong>find_namespace directive</strong> - The <code class="docutils literal notranslate"><span class="pre">find_namespace:</span></code> directive is supported since Python &gt;=3.3.</p>
</div>
<p>Notes:
1. In the <cite>package_data</cite> section, a key named with a single asterisk (<cite>*</cite>)
refers to all packages, in lieu of the empty string used in <cite>setup.py</cite>.</p>
</div>
</div>
<div class="section" id="configuration-api">
<h4><a class="toc-backref" href="#id52">Configuration API</a><a class="headerlink" href="#configuration-api" title="Permalink to this headline">¶</a></h4>
<p>Some automation tools may wish to access data from a configuration file.</p>
<p><code class="docutils literal notranslate"><span class="pre">Setuptools</span></code> exposes a <code class="docutils literal notranslate"><span class="pre">read_configuration()</span></code> function for
parsing <code class="docutils literal notranslate"><span class="pre">metadata</span></code> and <code class="docutils literal notranslate"><span class="pre">options</span></code> sections into a dictionary.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools.config</span> <span class="kn">import</span> <span class="n">read_configuration</span>

<span class="n">conf_dict</span> <span class="o">=</span> <span class="n">read_configuration</span><span class="p">(</span><span class="s2">&quot;/home/user/dev/package/setup.cfg&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>By default, <code class="docutils literal notranslate"><span class="pre">read_configuration()</span></code> will read only the file provided
in the first argument. To include values from other configuration files
which could be in various places, set the <code class="docutils literal notranslate"><span class="pre">find_others</span></code> keyword argument
to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
<p>If you have only a configuration file but not the whole package, you can still
try to get data out of it with the help of the <code class="docutils literal notranslate"><span class="pre">ignore_option_errors</span></code> keyword
argument. When it is set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, all options with errors possibly produced
by directives, such as <code class="docutils literal notranslate"><span class="pre">attr:</span></code> and others, will be silently ignored.
As a consequence, the resulting dictionary will include no such options.</p>
</div>
</div>
<div class="section" id="extending-and-reusing-setuptools">
<h3><a class="toc-backref" href="#id53">Extending and Reusing Setuptools</a><a class="headerlink" href="#extending-and-reusing-setuptools" title="Permalink to this headline">¶</a></h3>
<div class="section" id="creating-distutils-extensions">
<h4><a class="toc-backref" href="#id54">Creating <code class="docutils literal notranslate"><span class="pre">distutils</span></code> Extensions</a><a class="headerlink" href="#creating-distutils-extensions" title="Permalink to this headline">¶</a></h4>
<p>It can be hard to add new commands or setup arguments to the distutils.  But
the <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> package makes it a bit easier, by allowing you to distribute
a distutils extension as a separate project, and then have projects that need
the extension just refer to it in their <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> argument.</p>
<p>With <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>, your distutils extension projects can hook in new
commands and <code class="docutils literal notranslate"><span class="pre">setup()</span></code> arguments just by defining “entry points”.  These
are mappings from command or argument names to a specification of where to
import a handler from.  (See the section on <a class="reference internal" href="#dynamic-discovery-of-services-and-plugins">Dynamic Discovery of Services and
Plugins</a> above for some more background on entry points.)</p>
<div class="section" id="adding-commands">
<h5><a class="toc-backref" href="#id55">Adding Commands</a><a class="headerlink" href="#adding-commands" title="Permalink to this headline">¶</a></h5>
<p>You can add new <code class="docutils literal notranslate"><span class="pre">setup</span></code> commands by defining entry points in the
<code class="docutils literal notranslate"><span class="pre">distutils.commands</span></code> group.  For example, if you wanted to add a <code class="docutils literal notranslate"><span class="pre">foo</span></code>
command, you might add something like this to your distutils extension
project’s setup script:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;distutils.commands&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;foo = mypackage.some_module:foo&quot;</span><span class="p">,</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">)</span>
</pre></div>
</div>
<p>(Assuming, of course, that the <code class="docutils literal notranslate"><span class="pre">foo</span></code> class in <code class="docutils literal notranslate"><span class="pre">mypackage.some_module</span></code> is
a <code class="docutils literal notranslate"><span class="pre">setuptools.Command</span></code> subclass.)</p>
<p>Once a project containing such entry points has been activated on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>,
(e.g. by running “install” or “develop” with a site-packages installation
directory) the command(s) will be available to any <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>-based setup
scripts.  It is not necessary to use the <code class="docutils literal notranslate"><span class="pre">--command-packages</span></code> option or
to monkeypatch the <code class="docutils literal notranslate"><span class="pre">distutils.command</span></code> package to install your commands;
<code class="docutils literal notranslate"><span class="pre">setuptools</span></code> automatically adds a wrapper to the distutils to search for
entry points in the active distributions on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.  In fact, this is
how setuptools’ own commands are installed: the setuptools project’s setup
script defines entry points for them!</p>
</div>
<div class="section" id="adding-setup-arguments">
<h5><a class="toc-backref" href="#id56">Adding <code class="docutils literal notranslate"><span class="pre">setup()</span></code> Arguments</a><a class="headerlink" href="#adding-setup-arguments" title="Permalink to this headline">¶</a></h5>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Adding arguments to setup is discouraged as such arguments
are only supported through imperative execution and not supported through
declarative config.</p>
</div>
<p>Sometimes, your commands may need additional arguments to the <code class="docutils literal notranslate"><span class="pre">setup()</span></code>
call.  You can enable this by defining entry points in the
<code class="docutils literal notranslate"><span class="pre">distutils.setup_keywords</span></code> group.  For example, if you wanted a <code class="docutils literal notranslate"><span class="pre">setup()</span></code>
argument called <code class="docutils literal notranslate"><span class="pre">bar_baz</span></code>, you might add something like this to your
distutils extension project’s setup script:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;distutils.commands&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;foo = mypackage.some_module:foo&quot;</span><span class="p">,</span>
        <span class="p">],</span>
        <span class="s2">&quot;distutils.setup_keywords&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;bar_baz = mypackage.some_module:validate_bar_baz&quot;</span><span class="p">,</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The idea here is that the entry point defines a function that will be called
to validate the <code class="docutils literal notranslate"><span class="pre">setup()</span></code> argument, if it’s supplied.  The <code class="docutils literal notranslate"><span class="pre">Distribution</span></code>
object will have the initial value of the attribute set to <code class="docutils literal notranslate"><span class="pre">None</span></code>, and the
validation function will only be called if the <code class="docutils literal notranslate"><span class="pre">setup()</span></code> call sets it to
a non-None value.  Here’s an example validation function:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">assert_bool</span><span class="p">(</span><span class="n">dist</span><span class="p">,</span> <span class="n">attr</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Verify that value is True, False, 0, or 1&quot;&quot;&quot;</span>
    <span class="k">if</span> <span class="nb">bool</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="o">!=</span> <span class="n">value</span><span class="p">:</span>
        <span class="k">raise</span> <span class="n">DistutilsSetupError</span><span class="p">(</span>
            <span class="s2">&quot;</span><span class="si">%r</span><span class="s2"> must be a boolean value (got </span><span class="si">%r</span><span class="s2">)&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">attr</span><span class="p">,</span><span class="n">value</span><span class="p">)</span>
        <span class="p">)</span>
</pre></div>
</div>
<p>Your function should accept three arguments: the <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> object,
the attribute name, and the attribute value.  It should raise a
<code class="docutils literal notranslate"><span class="pre">DistutilsSetupError</span></code> (from the <code class="docutils literal notranslate"><span class="pre">distutils.errors</span></code> module) if the argument
is invalid.  Remember, your function will only be called with non-None values,
and the default value of arguments defined this way is always None.  So, your
commands should always be prepared for the possibility that the attribute will
be <code class="docutils literal notranslate"><span class="pre">None</span></code> when they access it later.</p>
<p>If more than one active distribution defines an entry point for the same
<code class="docutils literal notranslate"><span class="pre">setup()</span></code> argument, <em>all</em> of them will be called.  This allows multiple
distutils extensions to define a common argument, as long as they agree on
what values of that argument are valid.</p>
<p>Also note that as with commands, it is not necessary to subclass or monkeypatch
the distutils <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> class in order to add your arguments; it is
sufficient to define the entry points in your extension, as long as any setup
script using your extension lists your project in its <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code>
argument.</p>
</div>
<div class="section" id="customizing-distribution-options">
<h5><a class="toc-backref" href="#id57">Customizing Distribution Options</a><a class="headerlink" href="#customizing-distribution-options" title="Permalink to this headline">¶</a></h5>
<p>Plugins may wish to extend or alter the options on a Distribution object to
suit the purposes of that project. For example, a tool that infers the
<code class="docutils literal notranslate"><span class="pre">Distribution.version</span></code> from SCM-metadata may need to hook into the
option finalization. To enable this feature, Setuptools offers an entry
point “setuptools.finalize_distribution_options”. That entry point must
be a callable taking one argument (the Distribution instance).</p>
<p>If the callable has an <code class="docutils literal notranslate"><span class="pre">.order</span></code> property, that value will be used to
determine the order in which the hook is called. Lower numbers are called
first and the default is zero (0).</p>
<p>Plugins may read, alter, and set properties on the distribution, but each
plugin is encouraged to load the configuration/settings for their behavior
independently.</p>
</div>
<div class="section" id="adding-new-egg-info-files">
<h5><a class="toc-backref" href="#id58">Adding new EGG-INFO Files</a><a class="headerlink" href="#adding-new-egg-info-files" title="Permalink to this headline">¶</a></h5>
<p>Some extensible applications or frameworks may want to allow third parties to
develop plugins with application or framework-specific metadata included in
the plugins’ EGG-INFO directory, for easy access via the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>
metadata API.  The easiest way to allow this is to create a distutils extension
to be used from the plugin projects’ setup scripts (via <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code>)
that defines a new setup keyword, and then uses that data to write an EGG-INFO
file when the <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command is run.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command looks for extension points in an <code class="docutils literal notranslate"><span class="pre">egg_info.writers</span></code>
group, and calls them to write the files.  Here’s a simple example of a
distutils extension defining a setup argument <code class="docutils literal notranslate"><span class="pre">foo_bar</span></code>, which is a list of
lines that will be written to <code class="docutils literal notranslate"><span class="pre">foo_bar.txt</span></code> in the EGG-INFO directory of any
project that uses the argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;distutils.setup_keywords&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;foo_bar = setuptools.dist:assert_string_list&quot;</span><span class="p">,</span>
        <span class="p">],</span>
        <span class="s2">&quot;egg_info.writers&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;foo_bar.txt = setuptools.command.egg_info:write_arg&quot;</span><span class="p">,</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This simple example makes use of two utility functions defined by setuptools
for its own use: a routine to validate that a setup keyword is a sequence of
strings, and another one that looks up a setup argument and writes it to
a file.  Here’s what the writer utility looks like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">write_arg</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">basename</span><span class="p">,</span> <span class="n">filename</span><span class="p">):</span>
    <span class="n">argname</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">basename</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
    <span class="n">value</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">cmd</span><span class="o">.</span><span class="n">distribution</span><span class="p">,</span> <span class="n">argname</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
    <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
        <span class="n">value</span> <span class="o">=</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="o">+</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span>
    <span class="n">cmd</span><span class="o">.</span><span class="n">write_or_delete_file</span><span class="p">(</span><span class="n">argname</span><span class="p">,</span> <span class="n">filename</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
</pre></div>
</div>
<p>As you can see, <code class="docutils literal notranslate"><span class="pre">egg_info.writers</span></code> entry points must be a function taking
three arguments: a <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command instance, the basename of the file to
write (e.g. <code class="docutils literal notranslate"><span class="pre">foo_bar.txt</span></code>), and the actual full filename that should be
written to.</p>
<p>In general, writer functions should honor the command object’s <code class="docutils literal notranslate"><span class="pre">dry_run</span></code>
setting when writing files, and use the <code class="docutils literal notranslate"><span class="pre">distutils.log</span></code> object to do any
console output.  The easiest way to conform to this requirement is to use
the <code class="docutils literal notranslate"><span class="pre">cmd</span></code> object’s <code class="docutils literal notranslate"><span class="pre">write_file()</span></code>, <code class="docutils literal notranslate"><span class="pre">delete_file()</span></code>, and
<code class="docutils literal notranslate"><span class="pre">write_or_delete_file()</span></code> methods exclusively for your file operations.  See
those methods’ docstrings for more details.</p>
</div>
<div class="section" id="adding-support-for-revision-control-systems">
<h5><a class="toc-backref" href="#id59">Adding Support for Revision Control Systems</a><a class="headerlink" href="#adding-support-for-revision-control-systems" title="Permalink to this headline">¶</a></h5>
<p>If the files you want to include in the source distribution are tracked using
Git, Mercurial or SVN, you can use the following packages to achieve that:</p>
<ul class="simple">
<li>Git and Mercurial: <a class="reference external" href="https://pypi.org/project/setuptools_scm/">setuptools_scm</a></li>
<li>SVN: <a class="reference external" href="https://pypi.org/project/setuptools_svn/">setuptools_svn</a></li>
</ul>
<p>If you would like to create a plugin for <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> to find files tracked
by another revision control system, you can do so by adding an entry point to
the <code class="docutils literal notranslate"><span class="pre">setuptools.file_finders</span></code> group.  The entry point should be a function
accepting a single directory name, and should yield all the filenames within
that directory (and any subdirectories thereof) that are under revision
control.</p>
<p>For example, if you were going to create a plugin for a revision control system
called “foobar”, you would write a function something like this:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">find_files_for_foobar</span><span class="p">(</span><span class="n">dirname</span><span class="p">):</span>
    <span class="c1"># loop to yield paths that start with `dirname`</span>
</pre></div>
</div>
<p>And you would register it in a setup script using something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
    <span class="s2">&quot;setuptools.file_finders&quot;</span><span class="p">:</span> <span class="p">[</span>
        <span class="s2">&quot;foobar = my_foobar_module:find_files_for_foobar&quot;</span><span class="p">,</span>
    <span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Then, anyone who wants to use your plugin can simply install it, and their
local setuptools installation will be able to find the necessary files.</p>
<p>It is not necessary to distribute source control plugins with projects that
simply use the other source control system, or to specify the plugins in
<code class="docutils literal notranslate"><span class="pre">setup_requires</span></code>.  When you create a source distribution with the <code class="docutils literal notranslate"><span class="pre">sdist</span></code>
command, setuptools automatically records what files were found in the
<code class="docutils literal notranslate"><span class="pre">SOURCES.txt</span></code> file.  That way, recipients of source distributions don’t need
to have revision control at all.  However, if someone is working on a package
by checking out with that system, they will need the same plugin(s) that the
original author is using.</p>
<p>A few important points for writing revision control file finders:</p>
<ul class="simple">
<li>Your finder function MUST return relative paths, created by appending to the
passed-in directory name.  Absolute paths are NOT allowed, nor are relative
paths that reference a parent directory of the passed-in directory.</li>
<li>Your finder function MUST accept an empty string as the directory name,
meaning the current directory.  You MUST NOT convert this to a dot; just
yield relative paths.  So, yielding a subdirectory named <code class="docutils literal notranslate"><span class="pre">some/dir</span></code> under
the current directory should NOT be rendered as <code class="docutils literal notranslate"><span class="pre">./some/dir</span></code> or
<code class="docutils literal notranslate"><span class="pre">/somewhere/some/dir</span></code>, but <em>always</em> as simply <code class="docutils literal notranslate"><span class="pre">some/dir</span></code></li>
<li>Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefully
with the absence of needed programs (i.e., ones belonging to the revision
control system itself.  It <em>may</em>, however, use <code class="docutils literal notranslate"><span class="pre">distutils.log.warn()</span></code> to
inform the user of the missing program(s).</li>
</ul>
</div>
</div>
<div class="section" id="mailing-list-and-bug-tracker">
<h4><a class="toc-backref" href="#id60">Mailing List and Bug Tracker</a><a class="headerlink" href="#mailing-list-and-bug-tracker" title="Permalink to this headline">¶</a></h4>
<p>Please use the <a class="reference external" href="http://mail.python.org/pipermail/distutils-sig/">distutils-sig mailing list</a> for questions and discussion about
setuptools, and the <a class="reference external" href="https://github.com/pypa/setuptools/">setuptools bug tracker</a> ONLY for issues you have
confirmed via the list are actual bugs, and which you have reduced to a minimal
set of steps to reproduce.</p>
</div>
</div>
</div>
<span id="document-pkg_resources"></span><div class="section" id="package-discovery-and-resource-access-using-pkg-resources">
<h2><a class="toc-backref" href="#id2">Package Discovery and Resource Access using <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code></a><a class="headerlink" href="#package-discovery-and-resource-access-using-pkg-resources" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module distributed with <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> provides an API
for Python libraries to access their resource files, and for extensible
applications and frameworks to automatically discover plugins.  It also
provides runtime support for using C extensions that are inside zipfile-format
eggs, support for merging packages that have separately-distributed modules or
subpackages, and APIs for managing Python’s current “working set” of active
packages.</p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><strong>Table of Contents</strong></p>
<ul class="simple">
<li><a class="reference internal" href="#package-discovery-and-resource-access-using-pkg-resources" id="id2">Package Discovery and Resource Access using <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code></a><ul>
<li><a class="reference internal" href="#overview" id="id3">Overview</a></li>
<li><a class="reference internal" href="#api-reference" id="id4">API Reference</a><ul>
<li><a class="reference internal" href="#namespace-package-support" id="id5">Namespace Package Support</a></li>
<li><a class="reference internal" href="#workingset-objects" id="id6"><code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> Objects</a><ul>
<li><a class="reference internal" href="#basic-workingset-methods" id="id7">Basic <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> Methods</a></li>
<li><a class="reference internal" href="#workingset-methods-and-attributes" id="id8"><code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> Methods and Attributes</a></li>
<li><a class="reference internal" href="#receiving-change-notifications" id="id9">Receiving Change Notifications</a></li>
<li><a class="reference internal" href="#locating-plugins" id="id10">Locating Plugins</a></li>
</ul>
</li>
<li><a class="reference internal" href="#environment-objects" id="id11"><code class="docutils literal notranslate"><span class="pre">Environment</span></code> Objects</a></li>
<li><a class="reference internal" href="#requirement-objects" id="id12"><code class="docutils literal notranslate"><span class="pre">Requirement</span></code> Objects</a><ul>
<li><a class="reference internal" href="#requirements-parsing" id="id13">Requirements Parsing</a></li>
<li><a class="reference internal" href="#requirement-methods-and-attributes" id="id14"><code class="docutils literal notranslate"><span class="pre">Requirement</span></code> Methods and Attributes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#entry-points" id="id15">Entry Points</a><ul>
<li><a class="reference internal" href="#convenience-api" id="id16">Convenience API</a></li>
<li><a class="reference internal" href="#creating-and-parsing" id="id17">Creating and Parsing</a></li>
<li><a class="reference internal" href="#entrypoint-objects" id="id18"><code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> Objects</a></li>
</ul>
</li>
<li><a class="reference internal" href="#distribution-objects" id="id19"><code class="docutils literal notranslate"><span class="pre">Distribution</span></code> Objects</a><ul>
<li><a class="reference internal" href="#getting-or-creating-distributions" id="id20">Getting or Creating Distributions</a></li>
<li><a class="reference internal" href="#distribution-attributes" id="id21"><code class="docutils literal notranslate"><span class="pre">Distribution</span></code> Attributes</a></li>
<li><a class="reference internal" href="#distribution-methods" id="id22"><code class="docutils literal notranslate"><span class="pre">Distribution</span></code> Methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#resourcemanager-api" id="id23"><code class="docutils literal notranslate"><span class="pre">ResourceManager</span></code> API</a><ul>
<li><a class="reference internal" href="#basic-resource-access" id="id24">Basic Resource Access</a></li>
<li><a class="reference internal" href="#resource-extraction" id="id25">Resource Extraction</a></li>
<li><a class="reference internal" href="#provider-interface" id="id26">“Provider” Interface</a></li>
</ul>
</li>
<li><a class="reference internal" href="#metadata-api" id="id27">Metadata API</a><ul>
<li><a class="reference internal" href="#imetadataprovider-methods" id="id28"><code class="docutils literal notranslate"><span class="pre">IMetadataProvider</span></code> Methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#exceptions" id="id29">Exceptions</a></li>
<li><a class="reference internal" href="#supporting-custom-importers" id="id30">Supporting Custom Importers</a><ul>
<li><a class="reference internal" href="#iresourceprovider" id="id31">IResourceProvider</a></li>
<li><a class="reference internal" href="#built-in-resource-providers" id="id32">Built-in Resource Providers</a></li>
</ul>
</li>
<li><a class="reference internal" href="#utility-functions" id="id33">Utility Functions</a><ul>
<li><a class="reference internal" href="#parsing-utilities" id="id34">Parsing Utilities</a></li>
<li><a class="reference internal" href="#platform-utilities" id="id35">Platform Utilities</a></li>
<li><a class="reference internal" href="#pep-302-utilities" id="id36">PEP 302 Utilities</a></li>
<li><a class="reference internal" href="#file-path-utilities" id="id37">File/Path Utilities</a></li>
<li><a class="reference internal" href="#history" id="id38">History</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="overview">
<h3><a class="toc-backref" href="#id3">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module provides runtime facilities for finding,
introspecting, activating and using installed Python distributions. Some
of the more advanced features (notably the support for parallel installation
of multiple versions) rely specifically on the “egg” format (either as a
zip archive or subdirectory), while others (such as plugin discovery) will
work correctly so long as “egg-info” metadata directories are available for
relevant distributions.</p>
<p>Eggs are a distribution format for Python modules, similar in concept to
Java’s “jars” or Ruby’s “gems”, or the “wheel” format defined in PEP 427.
However, unlike a pure distribution format, eggs can also be installed and
added directly to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> as an import location. When installed in
this way, eggs are <em>discoverable</em>, meaning that they carry metadata that
unambiguously identifies their contents and dependencies. This means that
an installed egg can be <em>automatically</em> found and added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> in
response to simple requests of the form, “get me everything I need to use
docutils’ PDF support”. This feature allows mutually conflicting versions of
a distribution to co-exist in the same Python installation, with individual
applications activating the desired version at runtime by manipulating the
contents of <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> (this differs from the virtual environment
approach, which involves creating isolated environments for each
application).</p>
<p>The following terms are needed in order to explain the capabilities offered
by this module:</p>
<dl class="docutils">
<dt>project</dt>
<dd>A library, framework, script, plugin, application, or collection of data
or other resources, or some combination thereof.  Projects are assumed to
have “relatively unique” names, e.g. names registered with PyPI.</dd>
<dt>release</dt>
<dd>A snapshot of a project at a particular point in time, denoted by a version
identifier.</dd>
<dt>distribution</dt>
<dd>A file or files that represent a particular release.</dd>
<dt>importable distribution</dt>
<dd>A file or directory that, if placed on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, allows Python to
import any modules contained within it.</dd>
<dt>pluggable distribution</dt>
<dd>An importable distribution whose filename unambiguously identifies its
release (i.e. project and version), and whose contents unambiguously
specify what releases of other projects will satisfy its runtime
requirements.</dd>
<dt>extra</dt>
<dd>An “extra” is an optional feature of a release, that may impose additional
runtime requirements.  For example, if docutils PDF support required a
PDF support library to be present, docutils could define its PDF support as
an “extra”, and list what other project releases need to be available in
order to provide it.</dd>
<dt>environment</dt>
<dd>A collection of distributions potentially available for importing, but not
necessarily active.  More than one distribution (i.e. release version) for
a given project may be present in an environment.</dd>
<dt>working set</dt>
<dd>A collection of distributions actually available for importing, as on
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.  At most one distribution (release version) of a given
project may be present in a working set, as otherwise there would be
ambiguity as to what to import.</dd>
<dt>eggs</dt>
<dd>Eggs are pluggable distributions in one of the three formats currently
supported by <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>.  There are built eggs, development eggs,
and egg links.  Built eggs are directories or zipfiles whose name ends
with <code class="docutils literal notranslate"><span class="pre">.egg</span></code> and follows the egg naming conventions, and contain an
<code class="docutils literal notranslate"><span class="pre">EGG-INFO</span></code> subdirectory (zipped or otherwise).  Development eggs are
normal directories of Python code with one or more <code class="docutils literal notranslate"><span class="pre">ProjectName.egg-info</span></code>
subdirectories. The development egg format is also used to provide a
default version of a distribution that is available to software that
doesn’t use <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> to request specific versions. Egg links
are <code class="docutils literal notranslate"><span class="pre">*.egg-link</span></code> files that contain the name of a built or
development egg, to support symbolic linking on platforms that do not
have native symbolic links (or where the symbolic link support is
limited).</dd>
</dl>
<p>(For more information about these terms and concepts, see also this
<a class="reference external" href="http://mail.python.org/pipermail/distutils-sig/2005-June/004652.html">architectural overview</a> of <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> and Python Eggs in general.)</p>
</div>
<div class="section" id="api-reference">
<h3><a class="toc-backref" href="#id4">API Reference</a><a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h3>
<div class="section" id="namespace-package-support">
<h4><a class="toc-backref" href="#id5">Namespace Package Support</a><a class="headerlink" href="#namespace-package-support" title="Permalink to this headline">¶</a></h4>
<p>A namespace package is a package that only contains other packages and modules,
with no direct contents of its own.  Such packages can be split across
multiple, separately-packaged distributions.  They are normally used to split
up large packages produced by a single organization, such as in the <code class="docutils literal notranslate"><span class="pre">zope</span></code>
namespace package for Zope Corporation packages, and the <code class="docutils literal notranslate"><span class="pre">peak</span></code> namespace
package for the Python Enterprise Application Kit.</p>
<p>To create a namespace package, you list it in the <code class="docutils literal notranslate"><span class="pre">namespace_packages</span></code>
argument to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>, in your project’s <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>.  (See the
<a class="reference internal" href="index.html#namespace-packages"><span class="std std-ref">setuptools documentation on namespace packages</span></a> for
more information on this.)  Also, you must add a <code class="docutils literal notranslate"><span class="pre">declare_namespace()</span></code> call
in the package’s <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file(s):</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">declare_namespace(name)</span></code></dt>
<dd>Declare that the dotted package name <cite>name</cite> is a “namespace package” whose
contained packages and modules may be spread across multiple distributions.
The named package’s <code class="docutils literal notranslate"><span class="pre">__path__</span></code> will be extended to include the
corresponding package in all distributions on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> that contain a
package of that name.  (More precisely, if an importer’s
<code class="docutils literal notranslate"><span class="pre">find_module(name)</span></code> returns a loader, then it will also be searched for
the package’s contents.)  Whenever a Distribution’s <code class="docutils literal notranslate"><span class="pre">activate()</span></code> method
is invoked, it checks for the presence of namespace packages and updates
their <code class="docutils literal notranslate"><span class="pre">__path__</span></code> contents accordingly.</dd>
</dl>
<p>Applications that manipulate namespace packages or directly alter <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>
at runtime may also need to use this API function:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fixup_namespace_packages(path_item)</span></code></dt>
<dd>Declare that <cite>path_item</cite> is a newly added item on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> that may
need to be used to update existing namespace packages.  Ordinarily, this is
called for you when an egg is automatically added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, but if
your application modifies <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> to include locations that may
contain portions of a namespace package, you will need to call this
function to ensure they are added to the existing namespace packages.</dd>
</dl>
<p>Although by default <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> only supports namespace packages for
filesystem and zip importers, you can extend its support to other “importers”
compatible with PEP 302 using the <code class="docutils literal notranslate"><span class="pre">register_namespace_handler()</span></code> function.
See the section below on <a class="reference internal" href="#supporting-custom-importers">Supporting Custom Importers</a> for details.</p>
</div>
<div class="section" id="workingset-objects">
<h4><a class="toc-backref" href="#id6"><code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> Objects</a><a class="headerlink" href="#workingset-objects" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> class provides access to a collection of “active”
distributions.  In general, there is only one meaningful <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code>
instance: the one that represents the distributions that are currently active
on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.  This global instance is available under the name
<code class="docutils literal notranslate"><span class="pre">working_set</span></code> in the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module.  However, specialized
tools may wish to manipulate working sets that don’t correspond to
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, and therefore may wish to create other <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> instances.</p>
<p>It’s important to note that the global <code class="docutils literal notranslate"><span class="pre">working_set</span></code> object is initialized
from <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> when <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> is first imported, but is only updated
if you do all future <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> manipulation via <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> APIs.  If
you manually modify <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, you must invoke the appropriate methods on
the <code class="docutils literal notranslate"><span class="pre">working_set</span></code> instance to keep it in sync.  Unfortunately, Python does
not provide any way to detect arbitrary changes to a list object like
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, so <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> cannot automatically update the
<code class="docutils literal notranslate"><span class="pre">working_set</span></code> based on changes to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">WorkingSet(entries=None)</span></code></dt>
<dd><p class="first">Create a <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> from an iterable of path entries.  If <cite>entries</cite>
is not supplied, it defaults to the value of <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> at the time
the constructor is called.</p>
<p class="last">Note that you will not normally construct <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> instances
yourself, but instead you will implicitly or explicitly use the global
<code class="docutils literal notranslate"><span class="pre">working_set</span></code> instance.  For the most part, the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> API
is designed so that the <code class="docutils literal notranslate"><span class="pre">working_set</span></code> is used by default, such that you
don’t have to explicitly refer to it most of the time.</p>
</dd>
</dl>
<p>All distributions available directly on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> will be activated
automatically when <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> is imported. This behaviour can cause
version conflicts for applications which require non-default versions of
those distributions. To handle this situation, <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> checks for a
<code class="docutils literal notranslate"><span class="pre">__requires__</span></code> attribute in the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module when initializing the
default working set, and uses this to ensure a suitable version of each
affected distribution is activated. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">__requires__</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;CherryPy &lt; 3&quot;</span><span class="p">]</span> <span class="c1"># Must be set before pkg_resources import</span>
<span class="kn">import</span> <span class="nn">pkg_resources</span>
</pre></div>
</div>
<div class="section" id="basic-workingset-methods">
<h5><a class="toc-backref" href="#id7">Basic <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> Methods</a><a class="headerlink" href="#basic-workingset-methods" title="Permalink to this headline">¶</a></h5>
<p>The following methods of <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> objects are also available as module-
level functions in <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> that apply to the default <code class="docutils literal notranslate"><span class="pre">working_set</span></code>
instance.  Thus, you can use e.g. <code class="docutils literal notranslate"><span class="pre">pkg_resources.require()</span></code> as an
abbreviation for <code class="docutils literal notranslate"><span class="pre">pkg_resources.working_set.require()</span></code>:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">require(*requirements)</span></code></dt>
<dd><p class="first">Ensure that distributions matching <cite>requirements</cite> are activated</p>
<p><cite>requirements</cite> must be a string or a (possibly-nested) sequence
thereof, specifying the distributions and versions required.  The
return value is a sequence of the distributions that needed to be
activated to fulfill the requirements; all relevant distributions are
included, even if they were already activated in this working set.</p>
<p>For the syntax of requirement specifiers, see the section below on
<a class="reference internal" href="#requirements-parsing">Requirements Parsing</a>.</p>
<p>In general, it should not be necessary for you to call this method
directly.  It’s intended more for use in quick-and-dirty scripting and
interactive interpreter hacking than for production use. If you’re creating
an actual library or application, it’s strongly recommended that you create
a “setup.py” script using <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>, and declare all your requirements
there.  That way, tools like pip can automatically detect what requirements
your package has, and deal with them accordingly.</p>
<p class="last">Note that calling <code class="docutils literal notranslate"><span class="pre">require('SomePackage')</span></code> will not install
<code class="docutils literal notranslate"><span class="pre">SomePackage</span></code> if it isn’t already present.  If you need to do this, you
should use the <code class="docutils literal notranslate"><span class="pre">resolve()</span></code> method instead, which allows you to pass an
<code class="docutils literal notranslate"><span class="pre">installer</span></code> callback that will be invoked when a needed distribution
can’t be found on the local machine.  You can then have this callback
display a dialog, automatically download the needed distribution, or
whatever else is appropriate for your application. See the documentation
below on the <code class="docutils literal notranslate"><span class="pre">resolve()</span></code> method for more information, and also on the
<code class="docutils literal notranslate"><span class="pre">obtain()</span></code> method of <code class="docutils literal notranslate"><span class="pre">Environment</span></code> objects.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">run_script(requires,</span> <span class="pre">script_name)</span></code></dt>
<dd><p class="first">Locate distribution specified by <cite>requires</cite> and run its <cite>script_name</cite>
script.  <cite>requires</cite> must be a string containing a requirement specifier.
(See <a class="reference internal" href="#requirements-parsing">Requirements Parsing</a> below for the syntax.)</p>
<p>The script, if found, will be executed in <em>the caller’s globals</em>.  That’s
because this method is intended to be called from wrapper scripts that
act as a proxy for the “real” scripts in a distribution.  A wrapper script
usually doesn’t need to do anything but invoke this function with the
correct arguments.</p>
<p class="last">If you need more control over the script execution environment, you
probably want to use the <code class="docutils literal notranslate"><span class="pre">run_script()</span></code> method of a <code class="docutils literal notranslate"><span class="pre">Distribution</span></code>
object’s <a class="reference internal" href="#metadata-api">Metadata API</a> instead.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">iter_entry_points(group,</span> <span class="pre">name=None)</span></code></dt>
<dd><p class="first">Yield entry point objects from <cite>group</cite> matching <cite>name</cite></p>
<p>If <cite>name</cite> is None, yields all entry points in <cite>group</cite> from all
distributions in the working set, otherwise only ones matching both
<cite>group</cite> and <cite>name</cite> are yielded.  Entry points are yielded from the active
distributions in the order that the distributions appear in the working
set.  (For the global <code class="docutils literal notranslate"><span class="pre">working_set</span></code>, this should be the same as the order
that they are listed in <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.)  Note that within the entry points
advertised by an individual distribution, there is no particular ordering.</p>
<p class="last">Please see the section below on <a class="reference internal" href="#entry-points">Entry Points</a> for more information.</p>
</dd>
</dl>
</div>
<div class="section" id="workingset-methods-and-attributes">
<h5><a class="toc-backref" href="#id8"><code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> Methods and Attributes</a><a class="headerlink" href="#workingset-methods-and-attributes" title="Permalink to this headline">¶</a></h5>
<p>These methods are used to query or manipulate the contents of a specific
working set, so they must be explicitly invoked on a particular <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code>
instance:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">add_entry(entry)</span></code></dt>
<dd><p class="first">Add a path item to the <code class="docutils literal notranslate"><span class="pre">entries</span></code>, finding any distributions on it.  You
should use this when you add additional items to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> and you want
the global <code class="docutils literal notranslate"><span class="pre">working_set</span></code> to reflect the change.  This method is also
called by the <code class="docutils literal notranslate"><span class="pre">WorkingSet()</span></code> constructor during initialization.</p>
<p class="last">This method uses <code class="docutils literal notranslate"><span class="pre">find_distributions(entry,True)</span></code> to find distributions
corresponding to the path entry, and then <code class="docutils literal notranslate"><span class="pre">add()</span></code> them.  <cite>entry</cite> is
always appended to the <code class="docutils literal notranslate"><span class="pre">entries</span></code> attribute, even if it is already
present, however. (This is because <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> can contain the same value
more than once, and the <code class="docutils literal notranslate"><span class="pre">entries</span></code> attribute should be able to reflect
this.)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">__contains__(dist)</span></code></dt>
<dd>True if <cite>dist</cite> is active in this <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code>.  Note that only one
distribution for a given project can be active in a given <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">__iter__()</span></code></dt>
<dd>Yield distributions for non-duplicate projects in the working set.
The yield order is the order in which the items’ path entries were
added to the working set.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">find(req)</span></code></dt>
<dd>Find a distribution matching <cite>req</cite> (a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> instance).
If there is an active distribution for the requested project, this
returns it, as long as it meets the version requirement specified by
<cite>req</cite>.  But, if there is an active distribution for the project and it
does <em>not</em> meet the <cite>req</cite> requirement, <code class="docutils literal notranslate"><span class="pre">VersionConflict</span></code> is raised.
If there is no active distribution for the requested project, <code class="docutils literal notranslate"><span class="pre">None</span></code>
is returned.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">resolve(requirements,</span> <span class="pre">env=None,</span> <span class="pre">installer=None)</span></code></dt>
<dd><p class="first">List all distributions needed to (recursively) meet <cite>requirements</cite></p>
<p class="last"><cite>requirements</cite> must be a sequence of <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> objects.  <cite>env</cite>,
if supplied, should be an <code class="docutils literal notranslate"><span class="pre">Environment</span></code> instance.  If
not supplied, an <code class="docutils literal notranslate"><span class="pre">Environment</span></code> is created from the working set’s
<code class="docutils literal notranslate"><span class="pre">entries</span></code>.  <cite>installer</cite>, if supplied, will be invoked with each
requirement that cannot be met by an already-installed distribution; it
should return a <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> or <code class="docutils literal notranslate"><span class="pre">None</span></code>.  (See the <code class="docutils literal notranslate"><span class="pre">obtain()</span></code> method
of <a class="reference internal" href="#environment-objects">Environment Objects</a>, below, for more information on the <cite>installer</cite>
argument.)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">add(dist,</span> <span class="pre">entry=None)</span></code></dt>
<dd><p class="first">Add <cite>dist</cite> to working set, associated with <cite>entry</cite></p>
<p>If <cite>entry</cite> is unspecified, it defaults to <code class="docutils literal notranslate"><span class="pre">dist.location</span></code>.  On exit from
this routine, <cite>entry</cite> is added to the end of the working set’s <code class="docutils literal notranslate"><span class="pre">.entries</span></code>
(if it wasn’t already present).</p>
<p><cite>dist</cite> is only added to the working set if it’s for a project that
doesn’t already have a distribution active in the set.  If it’s
successfully added, any  callbacks registered with the <code class="docutils literal notranslate"><span class="pre">subscribe()</span></code>
method will be called.  (See <a class="reference internal" href="#receiving-change-notifications">Receiving Change Notifications</a>, below.)</p>
<p class="last">Note: <code class="docutils literal notranslate"><span class="pre">add()</span></code> is automatically called for you by the <code class="docutils literal notranslate"><span class="pre">require()</span></code>
method, so you don’t normally need to use this method directly.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">entries</span></code></dt>
<dd>This attribute represents a “shadow” <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, primarily useful for
debugging.  If you are experiencing import problems, you should check
the global <code class="docutils literal notranslate"><span class="pre">working_set</span></code> object’s <code class="docutils literal notranslate"><span class="pre">entries</span></code> against <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, to
ensure that they match.  If they do not, then some part of your program
is manipulating <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> without updating the <code class="docutils literal notranslate"><span class="pre">working_set</span></code>
accordingly.  IMPORTANT NOTE: do not directly manipulate this attribute!
Setting it equal to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> will not fix your problem, any more than
putting black tape over an “engine warning” light will fix your car!  If
this attribute is out of sync with <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, it’s merely an <em>indicator</em>
of the problem, not the cause of it.</dd>
</dl>
</div>
<div class="section" id="receiving-change-notifications">
<h5><a class="toc-backref" href="#id9">Receiving Change Notifications</a><a class="headerlink" href="#receiving-change-notifications" title="Permalink to this headline">¶</a></h5>
<p>Extensible applications and frameworks may need to receive notification when
a new distribution (such as a plug-in component) has been added to a working
set.  This is what the <code class="docutils literal notranslate"><span class="pre">subscribe()</span></code> method and <code class="docutils literal notranslate"><span class="pre">add_activation_listener()</span></code>
function are for.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">subscribe(callback)</span></code></dt>
<dd><p class="first">Invoke <code class="docutils literal notranslate"><span class="pre">callback(distribution)</span></code> once for each active distribution that is
in the set now, or gets added later.  Because the callback is invoked for
already-active distributions, you do not need to loop over the working set
yourself to deal with the existing items; just register the callback and
be prepared for the fact that it will be called immediately by this method.</p>
<p class="last">Note that callbacks <em>must not</em> allow exceptions to propagate, or they will
interfere with the operation of other callbacks and possibly result in an
inconsistent working set state.  Callbacks should use a try/except block
to ignore, log, or otherwise process any errors, especially since the code
that caused the callback to be invoked is unlikely to be able to handle
the errors any better than the callback itself.</p>
</dd>
</dl>
<p><code class="docutils literal notranslate"><span class="pre">pkg_resources.add_activation_listener()</span></code> is an alternate spelling of
<code class="docutils literal notranslate"><span class="pre">pkg_resources.working_set.subscribe()</span></code>.</p>
</div>
<div class="section" id="locating-plugins">
<h5><a class="toc-backref" href="#id10">Locating Plugins</a><a class="headerlink" href="#locating-plugins" title="Permalink to this headline">¶</a></h5>
<p>Extensible applications will sometimes have a “plugin directory” or a set of
plugin directories, from which they want to load entry points or other
metadata.  The <code class="docutils literal notranslate"><span class="pre">find_plugins()</span></code> method allows you to do this, by scanning an
environment for the newest version of each project that can be safely loaded
without conflicts or missing requirements.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">find_plugins(plugin_env,</span> <span class="pre">full_env=None,</span> <span class="pre">fallback=True)</span></code></dt>
<dd><p class="first">Scan <cite>plugin_env</cite> and identify which distributions could be added to this
working set without version conflicts or missing requirements.</p>
<p>Example usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">distributions</span><span class="p">,</span> <span class="n">errors</span> <span class="o">=</span> <span class="n">working_set</span><span class="o">.</span><span class="n">find_plugins</span><span class="p">(</span>
    <span class="n">Environment</span><span class="p">(</span><span class="n">plugin_dirlist</span><span class="p">)</span>
<span class="p">)</span>
<span class="nb">map</span><span class="p">(</span><span class="n">working_set</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="n">distributions</span><span class="p">)</span>  <span class="c1"># add plugins+libs to sys.path</span>
<span class="nb">print</span> <span class="s2">&quot;Couldn&#39;t load&quot;</span><span class="p">,</span> <span class="n">errors</span>        <span class="c1"># display errors</span>
</pre></div>
</div>
<p>The <cite>plugin_env</cite> should be an <code class="docutils literal notranslate"><span class="pre">Environment</span></code> instance that contains only
distributions that are in the project’s “plugin directory” or directories.
The <cite>full_env</cite>, if supplied, should be an <code class="docutils literal notranslate"><span class="pre">Environment</span></code> instance that
contains all currently-available distributions.</p>
<p>If <cite>full_env</cite> is not supplied, one is created automatically from the
<code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> this method is called on, which will typically mean that
every directory on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> will be scanned for distributions.</p>
<p>This method returns a 2-tuple: (<cite>distributions</cite>, <cite>error_info</cite>), where
<cite>distributions</cite> is a list of the distributions found in <cite>plugin_env</cite> that
were loadable, along with any other distributions that are needed to resolve
their dependencies.  <cite>error_info</cite> is a dictionary mapping unloadable plugin
distributions to an exception instance describing the error that occurred.
Usually this will be a <code class="docutils literal notranslate"><span class="pre">DistributionNotFound</span></code> or <code class="docutils literal notranslate"><span class="pre">VersionConflict</span></code>
instance.</p>
<p>Most applications will use this method mainly on the master <code class="docutils literal notranslate"><span class="pre">working_set</span></code>
instance in <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>, and then immediately add the returned
distributions to the working set so that they are available on sys.path.
This will make it possible to find any entry points, and allow any other
metadata tracking and hooks to be activated.</p>
<p>The resolution algorithm used by <code class="docutils literal notranslate"><span class="pre">find_plugins()</span></code> is as follows.  First,
the project names of the distributions present in <cite>plugin_env</cite> are sorted.
Then, each project’s eggs are tried in descending version order (i.e.,
newest version first).</p>
<p>An attempt is made to resolve each egg’s dependencies. If the attempt is
successful, the egg and its dependencies are added to the output list and to
a temporary copy of the working set.  The resolution process continues with
the next project name, and no older eggs for that project are tried.</p>
<p>If the resolution attempt fails, however, the error is added to the error
dictionary.  If the <cite>fallback</cite> flag is true, the next older version of the
plugin is tried, until a working version is found.  If false, the resolution
process continues with the next plugin project name.</p>
<p>Some applications may have stricter fallback requirements than others. For
example, an application that has a database schema or persistent objects
may not be able to safely downgrade a version of a package. Others may want
to ensure that a new plugin configuration is either 100% good or else
revert to a known-good configuration.  (That is, they may wish to revert to
a known configuration if the <cite>error_info</cite> return value is non-empty.)</p>
<p class="last">Note that this algorithm gives precedence to satisfying the dependencies of
alphabetically prior project names in case of version conflicts. If two
projects named “AaronsPlugin” and “ZekesPlugin” both need different versions
of “TomsLibrary”, then “AaronsPlugin” will win and “ZekesPlugin” will be
disabled due to version conflict.</p>
</dd>
</dl>
</div>
</div>
<div class="section" id="environment-objects">
<h4><a class="toc-backref" href="#id11"><code class="docutils literal notranslate"><span class="pre">Environment</span></code> Objects</a><a class="headerlink" href="#environment-objects" title="Permalink to this headline">¶</a></h4>
<p>An “environment” is a collection of <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects, usually ones
that are present and potentially importable on the current platform.
<code class="docutils literal notranslate"><span class="pre">Environment</span></code> objects are used by <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> to index available
distributions during dependency resolution.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">Environment(search_path=None,</span> <span class="pre">platform=get_supported_platform(),</span> <span class="pre">python=PY_MAJOR)</span></code></dt>
<dd><p class="first">Create an environment snapshot by scanning <cite>search_path</cite> for distributions
compatible with <cite>platform</cite> and <cite>python</cite>.  <cite>search_path</cite> should be a
sequence of strings such as might be used on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.  If a
<cite>search_path</cite> isn’t supplied, <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> is used.</p>
<p><cite>platform</cite> is an optional string specifying the name of the platform
that platform-specific distributions must be compatible with.  If
unspecified, it defaults to the current platform.  <cite>python</cite> is an
optional string naming the desired version of Python (e.g. <code class="docutils literal notranslate"><span class="pre">'2.4'</span></code>);
it defaults to the currently-running version.</p>
<p>You may explicitly set <cite>platform</cite> (and/or <cite>python</cite>) to <code class="docutils literal notranslate"><span class="pre">None</span></code> if you
wish to include <em>all</em> distributions, not just those compatible with the
running platform or Python version.</p>
<p class="last">Note that <cite>search_path</cite> is scanned immediately for distributions, and the
resulting <code class="docutils literal notranslate"><span class="pre">Environment</span></code> is a snapshot of the found distributions.  It
is not automatically updated if the system’s state changes due to e.g.
installation or removal of distributions.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">__getitem__(project_name)</span></code></dt>
<dd>Returns a list of distributions for the given project name, ordered
from newest to oldest version.  (And highest to lowest format precedence
for distributions that contain the same version of the project.)  If there
are no distributions for the project, returns an empty list.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">__iter__()</span></code></dt>
<dd>Yield the unique project names of the distributions in this environment.
The yielded names are always in lower case.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">add(dist)</span></code></dt>
<dd>Add <cite>dist</cite> to the environment if it matches the platform and python version
specified at creation time, and only if the distribution hasn’t already
been added. (i.e., adding the same distribution more than once is a no-op.)</dd>
<dt><code class="docutils literal notranslate"><span class="pre">remove(dist)</span></code></dt>
<dd>Remove <cite>dist</cite> from the environment.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">can_add(dist)</span></code></dt>
<dd>Is distribution <cite>dist</cite> acceptable for this environment?  If it’s not
compatible with the <code class="docutils literal notranslate"><span class="pre">platform</span></code> and <code class="docutils literal notranslate"><span class="pre">python</span></code> version values specified
when the environment was created, a false value is returned.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">__add__(dist_or_env)</span></code>  (<code class="docutils literal notranslate"><span class="pre">+</span></code> operator)</dt>
<dd>Add a distribution or environment to an <code class="docutils literal notranslate"><span class="pre">Environment</span></code> instance, returning
a <em>new</em> environment object that contains all the distributions previously
contained by both.  The new environment will have a <code class="docutils literal notranslate"><span class="pre">platform</span></code> and
<code class="docutils literal notranslate"><span class="pre">python</span></code> of <code class="docutils literal notranslate"><span class="pre">None</span></code>, meaning that it will not reject any distributions
from being added to it; it will simply accept whatever is added.  If you
want the added items to be filtered for platform and Python version, or
you want to add them to the <em>same</em> environment instance, you should use
in-place addition (<code class="docutils literal notranslate"><span class="pre">+=</span></code>) instead.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">__iadd__(dist_or_env)</span></code>  (<code class="docutils literal notranslate"><span class="pre">+=</span></code> operator)</dt>
<dd>Add a distribution or environment to an <code class="docutils literal notranslate"><span class="pre">Environment</span></code> instance
<em>in-place</em>, updating the existing instance and returning it.  The
<code class="docutils literal notranslate"><span class="pre">platform</span></code> and <code class="docutils literal notranslate"><span class="pre">python</span></code> filter attributes take effect, so distributions
in the source that do not have a suitable platform string or Python version
are silently ignored.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">best_match(req,</span> <span class="pre">working_set,</span> <span class="pre">installer=None)</span></code></dt>
<dd><p class="first">Find distribution best matching <cite>req</cite> and usable on <cite>working_set</cite></p>
<p class="last">This calls the <code class="docutils literal notranslate"><span class="pre">find(req)</span></code> method of the <cite>working_set</cite> to see if a
suitable distribution is already active.  (This may raise
<code class="docutils literal notranslate"><span class="pre">VersionConflict</span></code> if an unsuitable version of the project is already
active in the specified <cite>working_set</cite>.)  If a suitable distribution isn’t
active, this method returns the newest distribution in the environment
that meets the <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> in <cite>req</cite>.  If no suitable distribution is
found, and <cite>installer</cite> is supplied, then the result of calling
the environment’s <code class="docutils literal notranslate"><span class="pre">obtain(req,</span> <span class="pre">installer)</span></code> method will be returned.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">obtain(requirement,</span> <span class="pre">installer=None)</span></code></dt>
<dd>Obtain a distro that matches requirement (e.g. via download).  In the
base <code class="docutils literal notranslate"><span class="pre">Environment</span></code> class, this routine just returns
<code class="docutils literal notranslate"><span class="pre">installer(requirement)</span></code>, unless <cite>installer</cite> is None, in which case
None is returned instead.  This method is a hook that allows subclasses
to attempt other ways of obtaining a distribution before falling back
to the <cite>installer</cite> argument.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">scan(search_path=None)</span></code></dt>
<dd><p class="first">Scan <cite>search_path</cite> for distributions usable on <cite>platform</cite></p>
<p class="last">Any distributions found are added to the environment.  <cite>search_path</cite> should
be a sequence of strings such as might be used on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.  If not
supplied, <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> is used.  Only distributions conforming to
the platform/python version defined at initialization are added.  This
method is a shortcut for using the <code class="docutils literal notranslate"><span class="pre">find_distributions()</span></code> function to
find the distributions from each item in <cite>search_path</cite>, and then calling
<code class="docutils literal notranslate"><span class="pre">add()</span></code> to add each one to the environment.</p>
</dd>
</dl>
</div>
<div class="section" id="requirement-objects">
<h4><a class="toc-backref" href="#id12"><code class="docutils literal notranslate"><span class="pre">Requirement</span></code> Objects</a><a class="headerlink" href="#requirement-objects" title="Permalink to this headline">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">Requirement</span></code> objects express what versions of a project are suitable for
some purpose.  These objects (or their string form) are used by various
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> APIs in order to find distributions that a script or
distribution needs.</p>
<div class="section" id="requirements-parsing">
<h5><a class="toc-backref" href="#id13">Requirements Parsing</a><a class="headerlink" href="#requirements-parsing" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">parse_requirements(s)</span></code></dt>
<dd>Yield <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> objects for a string or iterable of lines.  Each
requirement must start on a new line.  See below for syntax.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Requirement.parse(s)</span></code></dt>
<dd><p class="first">Create a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> object from a string or iterable of lines.  A
<code class="docutils literal notranslate"><span class="pre">ValueError</span></code> is raised if the string or lines do not contain a valid
requirement specifier, or if they contain more than one specifier.  (To
parse multiple specifiers from a string or iterable of strings, use
<code class="docutils literal notranslate"><span class="pre">parse_requirements()</span></code> instead.)</p>
<p>The syntax of a requirement specifier is defined in full in PEP 508.</p>
<p>Some examples of valid requirement specifiers:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">FooProject</span> <span class="o">&gt;=</span> <span class="mf">1.2</span>
<span class="n">Fizzy</span> <span class="p">[</span><span class="n">foo</span><span class="p">,</span> <span class="n">bar</span><span class="p">]</span>
<span class="n">PickyThing</span><span class="o">&lt;</span><span class="mf">1.6</span><span class="p">,</span><span class="o">&gt;</span><span class="mf">1.9</span><span class="p">,</span><span class="o">!=</span><span class="mf">1.9</span><span class="o">.</span><span class="mi">6</span><span class="p">,</span><span class="o">&lt;</span><span class="mf">2.0</span><span class="n">a0</span><span class="p">,</span><span class="o">==</span><span class="mf">2.4</span><span class="n">c1</span>
<span class="n">SomethingWhoseVersionIDontCareAbout</span>
<span class="n">SomethingWithMarker</span><span class="p">[</span><span class="n">foo</span><span class="p">]</span><span class="o">&gt;</span><span class="mf">1.0</span><span class="p">;</span><span class="n">python_version</span><span class="o">&lt;</span><span class="s2">&quot;2.7&quot;</span>
</pre></div>
</div>
<p>The project name is the only required portion of a requirement string, and
if it’s the only thing supplied, the requirement will accept any version
of that project.</p>
<p>The “extras” in a requirement are used to request optional features of a
project, that may require additional project distributions in order to
function.  For example, if the hypothetical “Report-O-Rama” project offered
optional PDF support, it might require an additional library in order to
provide that support.  Thus, a project needing Report-O-Rama’s PDF features
could use a requirement of <code class="docutils literal notranslate"><span class="pre">Report-O-Rama[PDF]</span></code> to request installation
or activation of both Report-O-Rama and any libraries it needs in order to
provide PDF support.  For example, you could use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">Report</span><span class="o">-</span><span class="n">O</span><span class="o">-</span><span class="n">Rama</span><span class="p">[</span><span class="n">PDF</span><span class="p">]</span>
</pre></div>
</div>
<p>To install the necessary packages using pip, or call
<code class="docutils literal notranslate"><span class="pre">pkg_resources.require('Report-O-Rama[PDF]')</span></code> to add the necessary
distributions to sys.path at runtime.</p>
<p class="last">The “markers” in a requirement are used to specify when a requirement
should be installed – the requirement will be installed if the marker
evaluates as true in the current environment. For example, specifying
<code class="docutils literal notranslate"><span class="pre">argparse;python_version&lt;&quot;3.0&quot;</span></code> will not install in an Python 3
environment, but will in a Python 2 environment.</p>
</dd>
</dl>
</div>
<div class="section" id="requirement-methods-and-attributes">
<h5><a class="toc-backref" href="#id14"><code class="docutils literal notranslate"><span class="pre">Requirement</span></code> Methods and Attributes</a><a class="headerlink" href="#requirement-methods-and-attributes" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">__contains__(dist_or_version)</span></code></dt>
<dd><p class="first">Return true if <cite>dist_or_version</cite> fits the criteria for this requirement.
If <cite>dist_or_version</cite> is a <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> object, its project name must
match the requirement’s project name, and its version must meet the
requirement’s version criteria.  If <cite>dist_or_version</cite> is a string, it is
parsed using the <code class="docutils literal notranslate"><span class="pre">parse_version()</span></code> utility function.  Otherwise, it is
assumed to be an already-parsed version.</p>
<p class="last">The <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> object’s version specifiers (<code class="docutils literal notranslate"><span class="pre">.specs</span></code>) are internally
sorted into ascending version order, and used to establish what ranges of
versions are acceptable.  Adjacent redundant conditions are effectively
consolidated (e.g. <code class="docutils literal notranslate"><span class="pre">&quot;&gt;1,</span> <span class="pre">&gt;2&quot;</span></code> produces the same results as <code class="docutils literal notranslate"><span class="pre">&quot;&gt;2&quot;</span></code>, and
<code class="docutils literal notranslate"><span class="pre">&quot;&lt;2,&lt;3&quot;</span></code> produces the same results as <code class="docutils literal notranslate"><span class="pre">&quot;&lt;2&quot;</span></code>). <code class="docutils literal notranslate"><span class="pre">&quot;!=&quot;</span></code> versions are
excised from the ranges they fall within.  The version being tested for
acceptability is then checked for membership in the resulting ranges.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">__eq__(other_requirement)</span></code></dt>
<dd>A requirement compares equal to another requirement if they have
case-insensitively equal project names, version specifiers, and “extras”.
(The order that extras and version specifiers are in is also ignored.)
Equal requirements also have equal hashes, so that requirements can be
used in sets or as dictionary keys.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">__str__()</span></code></dt>
<dd>The string form of a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> is a string that, if passed to
<code class="docutils literal notranslate"><span class="pre">Requirement.parse()</span></code>, would return an equal <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> object.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">project_name</span></code></dt>
<dd>The name of the required project</dd>
<dt><code class="docutils literal notranslate"><span class="pre">key</span></code></dt>
<dd>An all-lowercase version of the <code class="docutils literal notranslate"><span class="pre">project_name</span></code>, useful for comparison
or indexing.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">extras</span></code></dt>
<dd>A tuple of names of “extras” that this requirement calls for.  (These will
be all-lowercase and normalized using the <code class="docutils literal notranslate"><span class="pre">safe_extra()</span></code> parsing utility
function, so they may not exactly equal the extras the requirement was
created with.)</dd>
<dt><code class="docutils literal notranslate"><span class="pre">specs</span></code></dt>
<dd>A list of <code class="docutils literal notranslate"><span class="pre">(op,version)</span></code> tuples, sorted in ascending parsed-version
order.  The <cite>op</cite> in each tuple is a comparison operator, represented as
a string.  The <cite>version</cite> is the (unparsed) version number.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">marker</span></code></dt>
<dd>An instance of <code class="docutils literal notranslate"><span class="pre">packaging.markers.Marker</span></code> that allows evaluation
against the current environment. May be None if no marker specified.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">url</span></code></dt>
<dd>The location to download the requirement from if specified.</dd>
</dl>
</div>
</div>
<div class="section" id="entry-points">
<h4><a class="toc-backref" href="#id15">Entry Points</a><a class="headerlink" href="#entry-points" title="Permalink to this headline">¶</a></h4>
<p>Entry points are a simple way for distributions to “advertise” Python objects
(such as functions or classes) for use by other distributions.  Extensible
applications and frameworks can search for entry points with a particular name
or group, either from a specific distribution or from all active distributions
on sys.path, and then inspect or load the advertised objects at will.</p>
<p>Entry points belong to “groups” which are named with a dotted name similar to
a Python package or module name.  For example, the <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> package uses
an entry point named <code class="docutils literal notranslate"><span class="pre">distutils.commands</span></code> in order to find commands defined
by distutils extensions.  <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> treats the names of entry points
defined in that group as the acceptable commands for a setup script.</p>
<p>In a similar way, other packages can define their own entry point groups,
either using dynamic names within the group (like <code class="docutils literal notranslate"><span class="pre">distutils.commands</span></code>), or
possibly using predefined names within the group.  For example, a blogging
framework that offers various pre- or post-publishing hooks might define an
entry point group and look for entry points named “pre_process” and
“post_process” within that group.</p>
<p>To advertise an entry point, a project needs to use <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> and provide
an <code class="docutils literal notranslate"><span class="pre">entry_points</span></code> argument to <code class="docutils literal notranslate"><span class="pre">setup()</span></code> in its setup script, so that the
entry points will be included in the distribution’s metadata.  For more
details, see the [<code class="docutils literal notranslate"><span class="pre">setuptools</span></code> documentation](<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins">https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins</a>).</p>
<p>Each project distribution can advertise at most one entry point of a given
name within the same entry point group.  For example, a distutils extension
could advertise two different <code class="docutils literal notranslate"><span class="pre">distutils.commands</span></code> entry points, as long as
they had different names.  However, there is nothing that prevents <em>different</em>
projects from advertising entry points of the same name in the same group.  In
some cases, this is a desirable thing, since the application or framework that
uses the entry points may be calling them as hooks, or in some other way
combining them.  It is up to the application or framework to decide what to do
if multiple distributions advertise an entry point; some possibilities include
using both entry points, displaying an error message, using the first one found
in sys.path order, etc.</p>
<div class="section" id="convenience-api">
<h5><a class="toc-backref" href="#id16">Convenience API</a><a class="headerlink" href="#convenience-api" title="Permalink to this headline">¶</a></h5>
<p>In the following functions, the <cite>dist</cite> argument can be a <code class="docutils literal notranslate"><span class="pre">Distribution</span></code>
instance, a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> instance, or a string specifying a requirement
(i.e. project name, version, etc.).  If the argument is a string or
<code class="docutils literal notranslate"><span class="pre">Requirement</span></code>, the specified distribution is located (and added to sys.path
if not already present).  An error will be raised if a matching distribution is
not available.</p>
<p>The <cite>group</cite> argument should be a string containing a dotted identifier,
identifying an entry point group.  If you are defining an entry point group,
you should include some portion of your package’s name in the group name so as
to avoid collision with other packages’ entry point groups.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">load_entry_point(dist,</span> <span class="pre">group,</span> <span class="pre">name)</span></code></dt>
<dd>Load the named entry point from the specified distribution, or raise
<code class="docutils literal notranslate"><span class="pre">ImportError</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">get_entry_info(dist,</span> <span class="pre">group,</span> <span class="pre">name)</span></code></dt>
<dd>Return an <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> object for the given <cite>group</cite> and <cite>name</cite> from
the specified distribution.  Returns <code class="docutils literal notranslate"><span class="pre">None</span></code> if the distribution has not
advertised a matching entry point.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">get_entry_map(dist,</span> <span class="pre">group=None)</span></code></dt>
<dd>Return the distribution’s entry point map for <cite>group</cite>, or the full entry
map for the distribution.  This function always returns a dictionary,
even if the distribution advertises no entry points.  If <cite>group</cite> is given,
the dictionary maps entry point names to the corresponding <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code>
object.  If <cite>group</cite> is None, the dictionary maps group names to
dictionaries that then map entry point names to the corresponding
<code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> instance in that group.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">iter_entry_points(group,</span> <span class="pre">name=None)</span></code></dt>
<dd><p class="first">Yield entry point objects from <cite>group</cite> matching <cite>name</cite>.</p>
<p>If <cite>name</cite> is None, yields all entry points in <cite>group</cite> from all
distributions in the working set on sys.path, otherwise only ones matching
both <cite>group</cite> and <cite>name</cite> are yielded.  Entry points are yielded from
the active distributions in the order that the distributions appear on
sys.path.  (Within entry points for a particular distribution, however,
there is no particular ordering.)</p>
<p class="last">(This API is actually a method of the global <code class="docutils literal notranslate"><span class="pre">working_set</span></code> object; see
the section above on <a class="reference internal" href="#basic-workingset-methods">Basic WorkingSet Methods</a> for more information.)</p>
</dd>
</dl>
</div>
<div class="section" id="creating-and-parsing">
<h5><a class="toc-backref" href="#id17">Creating and Parsing</a><a class="headerlink" href="#creating-and-parsing" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">EntryPoint(name,</span> <span class="pre">module_name,</span> <span class="pre">attrs=(),</span> <span class="pre">extras=(),</span> <span class="pre">dist=None)</span></code></dt>
<dd><p class="first">Create an <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> instance.  <cite>name</cite> is the entry point name.  The
<cite>module_name</cite> is the (dotted) name of the module containing the advertised
object.  <cite>attrs</cite> is an optional tuple of names to look up from the
module to obtain the advertised object.  For example, an <cite>attrs</cite> of
<code class="docutils literal notranslate"><span class="pre">(&quot;foo&quot;,&quot;bar&quot;)</span></code> and a <cite>module_name</cite> of <code class="docutils literal notranslate"><span class="pre">&quot;baz&quot;</span></code> would mean that the
advertised object could be obtained by the following code:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">baz</span>
<span class="n">advertised_object</span> <span class="o">=</span> <span class="n">baz</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">bar</span>
</pre></div>
</div>
<p class="last">The <cite>extras</cite> are an optional tuple of “extra feature” names that the
distribution needs in order to provide this entry point.  When the
entry point is loaded, these extra features are looked up in the <cite>dist</cite>
argument to find out what other distributions may need to be activated
on sys.path; see the <code class="docutils literal notranslate"><span class="pre">load()</span></code> method for more details.  The <cite>extras</cite>
argument is only meaningful if <cite>dist</cite> is specified.  <cite>dist</cite> must be
a <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> instance.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">EntryPoint.parse(src,</span> <span class="pre">dist=None)</span></code> (classmethod)</dt>
<dd><p class="first">Parse a single entry point from string <cite>src</cite></p>
<p>Entry point syntax follows the form:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">name</span> <span class="o">=</span> <span class="n">some</span><span class="o">.</span><span class="n">module</span><span class="p">:</span><span class="n">some</span><span class="o">.</span><span class="n">attr</span> <span class="p">[</span><span class="n">extra1</span><span class="p">,</span><span class="n">extra2</span><span class="p">]</span>
</pre></div>
</div>
<p class="last">The entry name and module name are required, but the <code class="docutils literal notranslate"><span class="pre">:attrs</span></code> and
<code class="docutils literal notranslate"><span class="pre">[extras]</span></code> parts are optional, as is the whitespace shown between
some of the items.  The <cite>dist</cite> argument is passed through to the
<code class="docutils literal notranslate"><span class="pre">EntryPoint()</span></code> constructor, along with the other values parsed from
<cite>src</cite>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">EntryPoint.parse_group(group,</span> <span class="pre">lines,</span> <span class="pre">dist=None)</span></code> (classmethod)</dt>
<dd>Parse <cite>lines</cite> (a string or sequence of lines) to create a dictionary
mapping entry point names to <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> objects.  <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> is
raised if entry point names are duplicated, if <cite>group</cite> is not a valid
entry point group name, or if there are any syntax errors.  (Note: the
<cite>group</cite> parameter is used only for validation and to create more
informative error messages.)  If <cite>dist</cite> is provided, it will be used to
set the <code class="docutils literal notranslate"><span class="pre">dist</span></code> attribute of the created <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> objects.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">EntryPoint.parse_map(data,</span> <span class="pre">dist=None)</span></code> (classmethod)</dt>
<dd>Parse <cite>data</cite> into a dictionary mapping group names to dictionaries mapping
entry point names to <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> objects.  If <cite>data</cite> is a dictionary,
then the keys are used as group names and the values are passed to
<code class="docutils literal notranslate"><span class="pre">parse_group()</span></code> as the <cite>lines</cite> argument.  If <cite>data</cite> is a string or
sequence of lines, it is first split into .ini-style sections (using
the <code class="docutils literal notranslate"><span class="pre">split_sections()</span></code> utility function) and the section names are used
as group names.  In either case, the <cite>dist</cite> argument is passed through to
<code class="docutils literal notranslate"><span class="pre">parse_group()</span></code> so that the entry points will be linked to the specified
distribution.</dd>
</dl>
</div>
<div class="section" id="entrypoint-objects">
<h5><a class="toc-backref" href="#id18"><code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> Objects</a><a class="headerlink" href="#entrypoint-objects" title="Permalink to this headline">¶</a></h5>
<p>For simple introspection, <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> objects have attributes that
correspond exactly to the constructor argument names: <code class="docutils literal notranslate"><span class="pre">name</span></code>,
<code class="docutils literal notranslate"><span class="pre">module_name</span></code>, <code class="docutils literal notranslate"><span class="pre">attrs</span></code>, <code class="docutils literal notranslate"><span class="pre">extras</span></code>, and <code class="docutils literal notranslate"><span class="pre">dist</span></code> are all available.  In
addition, the following methods are provided:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">load()</span></code></dt>
<dd>Load the entry point, returning the advertised Python object.  Effectively
calls <code class="docutils literal notranslate"><span class="pre">self.require()</span></code> then returns <code class="docutils literal notranslate"><span class="pre">self.resolve()</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">require(env=None,</span> <span class="pre">installer=None)</span></code></dt>
<dd>Ensure that any “extras” needed by the entry point are available on
sys.path.  <code class="docutils literal notranslate"><span class="pre">UnknownExtra</span></code> is raised if the <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> has <code class="docutils literal notranslate"><span class="pre">extras</span></code>,
but no <code class="docutils literal notranslate"><span class="pre">dist</span></code>, or if the named extras are not defined by the
distribution.  If <cite>env</cite> is supplied, it must be an <code class="docutils literal notranslate"><span class="pre">Environment</span></code>, and it
will be used to search for needed distributions if they are not already
present on sys.path.  If <cite>installer</cite> is supplied, it must be a callable
taking a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> instance and returning a matching importable
<code class="docutils literal notranslate"><span class="pre">Distribution</span></code> instance or None.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">resolve()</span></code></dt>
<dd>Resolve the entry point from its module and attrs, returning the advertised
Python object. Raises <code class="docutils literal notranslate"><span class="pre">ImportError</span></code> if it cannot be obtained.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">__str__()</span></code></dt>
<dd>The string form of an <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> is a string that could be passed to
<code class="docutils literal notranslate"><span class="pre">EntryPoint.parse()</span></code> to produce an equivalent <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code>.</dd>
</dl>
</div>
</div>
<div class="section" id="distribution-objects">
<h4><a class="toc-backref" href="#id19"><code class="docutils literal notranslate"><span class="pre">Distribution</span></code> Objects</a><a class="headerlink" href="#distribution-objects" title="Permalink to this headline">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects represent collections of Python code that may or may
not be importable, and may or may not have metadata and resources associated
with them.  Their metadata may include information such as what other projects
the distribution depends on, what entry points the distribution advertises, and
so on.</p>
<div class="section" id="getting-or-creating-distributions">
<h5><a class="toc-backref" href="#id20">Getting or Creating Distributions</a><a class="headerlink" href="#getting-or-creating-distributions" title="Permalink to this headline">¶</a></h5>
<p>Most commonly, you’ll obtain <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects from a <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> or
an <code class="docutils literal notranslate"><span class="pre">Environment</span></code>.  (See the sections above on <a class="reference internal" href="#workingset-objects">WorkingSet Objects</a> and
<a class="reference internal" href="#environment-objects">Environment Objects</a>, which are containers for active distributions and
available distributions, respectively.)  You can also obtain <code class="docutils literal notranslate"><span class="pre">Distribution</span></code>
objects from one of these high-level APIs:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">find_distributions(path_item,</span> <span class="pre">only=False)</span></code></dt>
<dd>Yield distributions accessible via <cite>path_item</cite>.  If <cite>only</cite> is true, yield
only distributions whose <code class="docutils literal notranslate"><span class="pre">location</span></code> is equal to <cite>path_item</cite>.  In other
words, if <cite>only</cite> is true, this yields any distributions that would be
importable if <cite>path_item</cite> were on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.  If <cite>only</cite> is false, this
also yields distributions that are “in” or “under” <cite>path_item</cite>, but would
not be importable unless their locations were also added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">get_distribution(dist_spec)</span></code></dt>
<dd>Return a <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> object for a given <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> or string.
If <cite>dist_spec</cite> is already a <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> instance, it is returned.
If it is a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> object or a string that can be parsed into one,
it is used to locate and activate a matching distribution, which is then
returned.</dd>
</dl>
<p>However, if you’re creating specialized tools for working with distributions,
or creating a new distribution format, you may also need to create
<code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects directly, using one of the three constructors below.</p>
<p>These constructors all take an optional <cite>metadata</cite> argument, which is used to
access any resources or metadata associated with the distribution.  <cite>metadata</cite>
must be an object that implements the <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> interface, or None.
If it is None, an <code class="docutils literal notranslate"><span class="pre">EmptyProvider</span></code> is used instead.  <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects
implement both the <a class="reference internal" href="#iresourceprovider">IResourceProvider</a> and <a class="reference internal" href="#imetadataprovider-methods">IMetadataProvider Methods</a> by
delegating them to the <cite>metadata</cite> object.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">Distribution.from_location(location,</span> <span class="pre">basename,</span> <span class="pre">metadata=None,</span> <span class="pre">**kw)</span></code> (classmethod)</dt>
<dd>Create a distribution for <cite>location</cite>, which must be a string such as a
URL, filename, or other string that might be used on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.
<cite>basename</cite> is a string naming the distribution, like <code class="docutils literal notranslate"><span class="pre">Foo-1.2-py2.4.egg</span></code>.
If <cite>basename</cite> ends with <code class="docutils literal notranslate"><span class="pre">.egg</span></code>, then the project’s name, version, python
version and platform are extracted from the filename and used to set those
properties of the created distribution.  Any additional keyword arguments
are forwarded to the <code class="docutils literal notranslate"><span class="pre">Distribution()</span></code> constructor.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Distribution.from_filename(filename,</span> <span class="pre">metadata=None**kw)</span></code> (classmethod)</dt>
<dd>Create a distribution by parsing a local filename.  This is a shorter way
of saying  <code class="docutils literal notranslate"><span class="pre">Distribution.from_location(normalize_path(filename),</span>
<span class="pre">os.path.basename(filename),</span> <span class="pre">metadata)</span></code>.  In other words, it creates a
distribution whose location is the normalize form of the filename, parsing
name and version information from the base portion of the filename.  Any
additional keyword arguments are forwarded to the <code class="docutils literal notranslate"><span class="pre">Distribution()</span></code>
constructor.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Distribution(location,metadata,project_name,version,py_version,platform,precedence)</span></code></dt>
<dd>Create a distribution by setting its properties.  All arguments are
optional and default to None, except for <cite>py_version</cite> (which defaults to
the current Python version) and <cite>precedence</cite> (which defaults to
<code class="docutils literal notranslate"><span class="pre">EGG_DIST</span></code>; for more details see <code class="docutils literal notranslate"><span class="pre">precedence</span></code> under <a class="reference internal" href="#distribution-attributes">Distribution
Attributes</a> below).  Note that it’s usually easier to use the
<code class="docutils literal notranslate"><span class="pre">from_filename()</span></code> or <code class="docutils literal notranslate"><span class="pre">from_location()</span></code> constructors than to specify
all these arguments individually.</dd>
</dl>
</div>
<div class="section" id="distribution-attributes">
<h5><a class="toc-backref" href="#id21"><code class="docutils literal notranslate"><span class="pre">Distribution</span></code> Attributes</a><a class="headerlink" href="#distribution-attributes" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt>location</dt>
<dd>A string indicating the distribution’s location.  For an importable
distribution, this is the string that would be added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> to
make it actively importable.  For non-importable distributions, this is
simply a filename, URL, or other way of locating the distribution.</dd>
<dt>project_name</dt>
<dd>A string, naming the project that this distribution is for.  Project names
are defined by a project’s setup script, and they are used to identify
projects on PyPI.  When a <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> is constructed, the
<cite>project_name</cite> argument is passed through the <code class="docutils literal notranslate"><span class="pre">safe_name()</span></code> utility
function to filter out any unacceptable characters.</dd>
<dt>key</dt>
<dd><code class="docutils literal notranslate"><span class="pre">dist.key</span></code> is short for <code class="docutils literal notranslate"><span class="pre">dist.project_name.lower()</span></code>.  It’s used for
case-insensitive comparison and indexing of distributions by project name.</dd>
<dt>extras</dt>
<dd>A list of strings, giving the names of extra features defined by the
project’s dependency list (the <code class="docutils literal notranslate"><span class="pre">extras_require</span></code> argument specified in
the project’s setup script).</dd>
<dt>version</dt>
<dd>A string denoting what release of the project this distribution contains.
When a <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> is constructed, the <cite>version</cite> argument is passed
through the <code class="docutils literal notranslate"><span class="pre">safe_version()</span></code> utility function to filter out any
unacceptable characters.  If no <cite>version</cite> is specified at construction
time, then attempting to access this attribute later will cause the
<code class="docutils literal notranslate"><span class="pre">Distribution</span></code> to try to discover its version by reading its <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code>
metadata file.  If <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> is unavailable or can’t be parsed,
<code class="docutils literal notranslate"><span class="pre">ValueError</span></code> is raised.</dd>
<dt>parsed_version</dt>
<dd>The <code class="docutils literal notranslate"><span class="pre">parsed_version</span></code> is an object representing a “parsed” form of the
distribution’s <code class="docutils literal notranslate"><span class="pre">version</span></code>.  <code class="docutils literal notranslate"><span class="pre">dist.parsed_version</span></code> is a shortcut for
calling <code class="docutils literal notranslate"><span class="pre">parse_version(dist.version)</span></code>.  It is used to compare or sort
distributions by version.  (See the <a class="reference internal" href="#parsing-utilities">Parsing Utilities</a> section below for
more information on the <code class="docutils literal notranslate"><span class="pre">parse_version()</span></code> function.)  Note that accessing
<code class="docutils literal notranslate"><span class="pre">parsed_version</span></code> may result in a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> if the <code class="docutils literal notranslate"><span class="pre">Distribution</span></code>
was constructed without a <cite>version</cite> and without <cite>metadata</cite> capable of
supplying the missing version info.</dd>
<dt>py_version</dt>
<dd>The major/minor Python version the distribution supports, as a string.
For example, “2.7” or “3.4”.  The default is the current version of Python.</dd>
<dt>platform</dt>
<dd>A string representing the platform the distribution is intended for, or
<code class="docutils literal notranslate"><span class="pre">None</span></code> if the distribution is “pure Python” and therefore cross-platform.
See <a class="reference internal" href="#platform-utilities">Platform Utilities</a> below for more information on platform strings.</dd>
<dt>precedence</dt>
<dd>A distribution’s <code class="docutils literal notranslate"><span class="pre">precedence</span></code> is used to determine the relative order of
two distributions that have the same <code class="docutils literal notranslate"><span class="pre">project_name</span></code> and
<code class="docutils literal notranslate"><span class="pre">parsed_version</span></code>.  The default precedence is <code class="docutils literal notranslate"><span class="pre">pkg_resources.EGG_DIST</span></code>,
which is the highest (i.e. most preferred) precedence.  The full list
of predefined precedences, from most preferred to least preferred, is:
<code class="docutils literal notranslate"><span class="pre">EGG_DIST</span></code>, <code class="docutils literal notranslate"><span class="pre">BINARY_DIST</span></code>, <code class="docutils literal notranslate"><span class="pre">SOURCE_DIST</span></code>, <code class="docutils literal notranslate"><span class="pre">CHECKOUT_DIST</span></code>, and
<code class="docutils literal notranslate"><span class="pre">DEVELOP_DIST</span></code>.  Normally, precedences other than <code class="docutils literal notranslate"><span class="pre">EGG_DIST</span></code> are used
only by the <code class="docutils literal notranslate"><span class="pre">setuptools.package_index</span></code> module, when sorting distributions
found in a package index to determine their suitability for installation.
“System” and “Development” eggs (i.e., ones that use the <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code>
format), however, are automatically given a precedence of <code class="docutils literal notranslate"><span class="pre">DEVELOP_DIST</span></code>.</dd>
</dl>
</div>
<div class="section" id="distribution-methods">
<h5><a class="toc-backref" href="#id22"><code class="docutils literal notranslate"><span class="pre">Distribution</span></code> Methods</a><a class="headerlink" href="#distribution-methods" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">activate(path=None)</span></code></dt>
<dd><p class="first">Ensure distribution is importable on <cite>path</cite>.  If <cite>path</cite> is None,
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> is used instead.  This ensures that the distribution’s
<code class="docutils literal notranslate"><span class="pre">location</span></code> is in the <cite>path</cite> list, and it also performs any necessary
namespace package fixups or declarations.  (That is, if the distribution
contains namespace packages, this method ensures that they are declared,
and that the distribution’s contents for those namespace packages are
merged with the contents provided by any other active distributions.  See
the section above on <a class="reference internal" href="#namespace-package-support">Namespace Package Support</a> for more information.)</p>
<p class="last"><code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> adds a notification callback to the global <code class="docutils literal notranslate"><span class="pre">working_set</span></code>
that ensures this method is called whenever a distribution is added to it.
Therefore, you should not normally need to explicitly call this method.
(Note that this means that namespace packages on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> are always
imported as soon as <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> is, which is another reason why
namespace packages should not contain any code or import statements.)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">as_requirement()</span></code></dt>
<dd>Return a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> instance that matches this distribution’s project
name and version.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">requires(extras=())</span></code></dt>
<dd>List the <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> objects that specify this distribution’s
dependencies.  If <cite>extras</cite> is specified, it should be a sequence of names
of “extras” defined by the distribution, and the list returned will then
include any dependencies needed to support the named “extras”.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">clone(**kw)</span></code></dt>
<dd>Create a copy of the distribution.  Any supplied keyword arguments override
the corresponding argument to the <code class="docutils literal notranslate"><span class="pre">Distribution()</span></code> constructor, allowing
you to change some of the copied distribution’s attributes.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">egg_name()</span></code></dt>
<dd>Return what this distribution’s standard filename should be, not including
the “.egg” extension.  For example, a distribution for project “Foo”
version 1.2 that runs on Python 2.3 for Windows would have an <code class="docutils literal notranslate"><span class="pre">egg_name()</span></code>
of <code class="docutils literal notranslate"><span class="pre">Foo-1.2-py2.3-win32</span></code>.  Any dashes in the name or version are
converted to underscores.  (<code class="docutils literal notranslate"><span class="pre">Distribution.from_location()</span></code> will convert
them back when parsing a “.egg” file name.)</dd>
<dt><code class="docutils literal notranslate"><span class="pre">__cmp__(other)</span></code>, <code class="docutils literal notranslate"><span class="pre">__hash__()</span></code></dt>
<dd>Distribution objects are hashed and compared on the basis of their parsed
version and precedence, followed by their key (lowercase project name),
location, Python version, and platform.</dd>
</dl>
<p>The following methods are used to access <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> objects advertised
by the distribution.  See the section above on <a class="reference internal" href="#entry-points">Entry Points</a> for more
detailed information about these operations:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">get_entry_info(group,</span> <span class="pre">name)</span></code></dt>
<dd>Return the <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code> object for <cite>group</cite> and <cite>name</cite>, or None if no
such point is advertised by this distribution.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">get_entry_map(group=None)</span></code></dt>
<dd>Return the entry point map for <cite>group</cite>.  If <cite>group</cite> is None, return
a dictionary mapping group names to entry point maps for all groups.
(An entry point map is a dictionary of entry point names to <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code>
objects.)</dd>
<dt><code class="docutils literal notranslate"><span class="pre">load_entry_point(group,</span> <span class="pre">name)</span></code></dt>
<dd>Short for <code class="docutils literal notranslate"><span class="pre">get_entry_info(group,</span> <span class="pre">name).load()</span></code>.  Returns the object
advertised by the named entry point, or raises <code class="docutils literal notranslate"><span class="pre">ImportError</span></code> if
the entry point isn’t advertised by this distribution, or there is some
other import problem.</dd>
</dl>
<p>In addition to the above methods, <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects also implement all
of the <a class="reference internal" href="#iresourceprovider">IResourceProvider</a> and <a class="reference internal" href="#imetadataprovider-methods">IMetadataProvider Methods</a> (which are
documented in later sections):</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">has_metadata(name)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">metadata_isdir(name)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">metadata_listdir(name)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">get_metadata(name)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">get_metadata_lines(name)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">run_script(script_name,</span> <span class="pre">namespace)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">get_resource_filename(manager,</span> <span class="pre">resource_name)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">get_resource_stream(manager,</span> <span class="pre">resource_name)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">get_resource_string(manager,</span> <span class="pre">resource_name)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">has_resource(resource_name)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">resource_isdir(resource_name)</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">resource_listdir(resource_name)</span></code></li>
</ul>
<p>If the distribution was created with a <cite>metadata</cite> argument, these resource and
metadata access methods are all delegated to that <cite>metadata</cite> provider.
Otherwise, they are delegated to an <code class="docutils literal notranslate"><span class="pre">EmptyProvider</span></code>, so that the distribution
will appear to have no resources or metadata.  This delegation approach is used
so that supporting custom importers or new distribution formats can be done
simply by creating an appropriate <a class="reference internal" href="#iresourceprovider">IResourceProvider</a> implementation; see the
section below on <a class="reference internal" href="#supporting-custom-importers">Supporting Custom Importers</a> for more details.</p>
</div>
</div>
<div class="section" id="resourcemanager-api">
<span id="id1"></span><h4><a class="toc-backref" href="#id23"><code class="docutils literal notranslate"><span class="pre">ResourceManager</span></code> API</a><a class="headerlink" href="#resourcemanager-api" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">ResourceManager</span></code> class provides uniform access to package resources,
whether those resources exist as files and directories or are compressed in
an archive of some kind.</p>
<p>Normally, you do not need to create or explicitly manage <code class="docutils literal notranslate"><span class="pre">ResourceManager</span></code>
instances, as the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module creates a global instance for you,
and makes most of its methods available as top-level names in the
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module namespace.  So, for example, this code actually
calls the <code class="docutils literal notranslate"><span class="pre">resource_string()</span></code> method of the global <code class="docutils literal notranslate"><span class="pre">ResourceManager</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">pkg_resources</span>
<span class="n">my_data</span> <span class="o">=</span> <span class="n">pkg_resources</span><span class="o">.</span><span class="n">resource_string</span><span class="p">(</span><span class="vm">__name__</span><span class="p">,</span> <span class="s2">&quot;foo.dat&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Thus, you can use the APIs below without needing an explicit
<code class="docutils literal notranslate"><span class="pre">ResourceManager</span></code> instance; just import and use them as needed.</p>
<div class="section" id="basic-resource-access">
<h5><a class="toc-backref" href="#id24">Basic Resource Access</a><a class="headerlink" href="#basic-resource-access" title="Permalink to this headline">¶</a></h5>
<p>In the following methods, the <cite>package_or_requirement</cite> argument may be either
a Python package/module name (e.g. <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code>) or a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> instance.
If it is a package or module name, the named module or package must be
importable (i.e., be in a distribution or directory on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>), and the
<cite>resource_name</cite> argument is interpreted relative to the named package.  (Note
that if a module name is used, then the resource name is relative to the
package immediately containing the named module.  Also, you should not use use
a namespace package name, because a namespace package can be spread across
multiple distributions, and is therefore ambiguous as to which distribution
should be searched for the resource.)</p>
<p>If it is a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code>, then the requirement is automatically resolved
(searching the current <code class="docutils literal notranslate"><span class="pre">Environment</span></code> if necessary) and a matching
distribution is added to the <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> if one was not
already present.  (Unless the <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> can’t be satisfied, in which
case an exception is raised.)  The <cite>resource_name</cite> argument is then interpreted
relative to the root of the identified distribution; i.e. its first path
segment will be treated as a peer of the top-level modules or packages in the
distribution.</p>
<p>Note that resource names must be <code class="docutils literal notranslate"><span class="pre">/</span></code>-separated paths rooted at the package,
cannot contain relative names like <code class="docutils literal notranslate"><span class="pre">&quot;..&quot;</span></code>, and cannot be absolute.  Do <em>not</em> use
<code class="docutils literal notranslate"><span class="pre">os.path</span></code> routines to manipulate resource paths, as they are <em>not</em> filesystem
paths.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">resource_exists(package_or_requirement,</span> <span class="pre">resource_name)</span></code></dt>
<dd>Does the named resource exist?  Return <code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">False</span></code> accordingly.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">resource_stream(package_or_requirement,</span> <span class="pre">resource_name)</span></code></dt>
<dd>Return a readable file-like object for the specified resource; it may be
an actual file, a <code class="docutils literal notranslate"><span class="pre">StringIO</span></code>, or some similar object.  The stream is
in “binary mode”, in the sense that whatever bytes are in the resource
will be read as-is.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">resource_string(package_or_requirement,</span> <span class="pre">resource_name)</span></code></dt>
<dd>Return the specified resource as a string.  The resource is read in
binary fashion, such that the returned string contains exactly the bytes
that are stored in the resource.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">resource_isdir(package_or_requirement,</span> <span class="pre">resource_name)</span></code></dt>
<dd>Is the named resource a directory?  Return <code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">False</span></code>
accordingly.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">resource_listdir(package_or_requirement,</span> <span class="pre">resource_name)</span></code></dt>
<dd>List the contents of the named resource directory, just like <code class="docutils literal notranslate"><span class="pre">os.listdir</span></code>
except that it works even if the resource is in a zipfile.</dd>
</dl>
<p>Note that only <code class="docutils literal notranslate"><span class="pre">resource_exists()</span></code> and <code class="docutils literal notranslate"><span class="pre">resource_isdir()</span></code> are insensitive
as to the resource type.  You cannot use <code class="docutils literal notranslate"><span class="pre">resource_listdir()</span></code> on a file
resource, and you can’t use <code class="docutils literal notranslate"><span class="pre">resource_string()</span></code> or <code class="docutils literal notranslate"><span class="pre">resource_stream()</span></code> on
directory resources.  Using an inappropriate method for the resource type may
result in an exception or undefined behavior, depending on the platform and
distribution format involved.</p>
</div>
<div class="section" id="resource-extraction">
<h5><a class="toc-backref" href="#id25">Resource Extraction</a><a class="headerlink" href="#resource-extraction" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">resource_filename(package_or_requirement,</span> <span class="pre">resource_name)</span></code></dt>
<dd><p class="first">Sometimes, it is not sufficient to access a resource in string or stream
form, and a true filesystem filename is needed.  In such cases, you can
use this method (or module-level function) to obtain a filename for a
resource.  If the resource is in an archive distribution (such as a zipped
egg), it will be extracted to a cache directory, and the filename within
the cache will be returned.  If the named resource is a directory, then
all resources within that directory (including subdirectories) are also
extracted.  If the named resource is a C extension or “eager resource”
(see the <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> documentation for details), then all C extensions
and eager resources are extracted at the same time.</p>
<p class="last">Archived resources are extracted to a cache location that can be managed by
the following two methods:</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">set_extraction_path(path)</span></code></dt>
<dd><p class="first">Set the base path where resources will be extracted to, if needed.</p>
<p>If you do not call this routine before any extractions take place, the
path defaults to the return value of <code class="docutils literal notranslate"><span class="pre">get_default_cache()</span></code>.  (Which is
based on the <code class="docutils literal notranslate"><span class="pre">PYTHON_EGG_CACHE</span></code> environment variable, with various
platform-specific fallbacks.  See that routine’s documentation for more
details.)</p>
<p>Resources are extracted to subdirectories of this path based upon
information given by the resource provider.  You may set this to a
temporary directory, but then you must call <code class="docutils literal notranslate"><span class="pre">cleanup_resources()</span></code> to
delete the extracted files when done.  There is no guarantee that
<code class="docutils literal notranslate"><span class="pre">cleanup_resources()</span></code> will be able to remove all extracted files.  (On
Windows, for example, you can’t unlink .pyd or .dll files that are still
in use.)</p>
<p class="last">Note that you may not change the extraction path for a given resource
manager once resources have been extracted, unless you first call
<code class="docutils literal notranslate"><span class="pre">cleanup_resources()</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">cleanup_resources(force=False)</span></code></dt>
<dd>Delete all extracted resource files and directories, returning a list
of the file and directory names that could not be successfully removed.
This function does not have any concurrency protection, so it should
generally only be called when the extraction path is a temporary
directory exclusive to a single process.  This method is not
automatically called; you must call it explicitly or register it as an
<code class="docutils literal notranslate"><span class="pre">atexit</span></code> function if you wish to ensure cleanup of a temporary
directory used for extractions.</dd>
</dl>
</div>
<div class="section" id="provider-interface">
<h5><a class="toc-backref" href="#id26">“Provider” Interface</a><a class="headerlink" href="#provider-interface" title="Permalink to this headline">¶</a></h5>
<p>If you are implementing an <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> and/or <code class="docutils literal notranslate"><span class="pre">IMetadataProvider</span></code>
for a new distribution archive format, you may need to use the following
<code class="docutils literal notranslate"><span class="pre">IResourceManager</span></code> methods to co-ordinate extraction of resources to the
filesystem.  If you’re not implementing an archive format, however, you have
no need to use these methods.  Unlike the other methods listed above, they are
<em>not</em> available as top-level functions tied to the global <code class="docutils literal notranslate"><span class="pre">ResourceManager</span></code>;
you must therefore have an explicit <code class="docutils literal notranslate"><span class="pre">ResourceManager</span></code> instance to use them.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">get_cache_path(archive_name,</span> <span class="pre">names=())</span></code></dt>
<dd><p class="first">Return absolute location in cache for <cite>archive_name</cite> and <cite>names</cite></p>
<p>The parent directory of the resulting path will be created if it does
not already exist.  <cite>archive_name</cite> should be the base filename of the
enclosing egg (which may not be the name of the enclosing zipfile!),
including its “.egg” extension.  <cite>names</cite>, if provided, should be a
sequence of path name parts “under” the egg’s extraction location.</p>
<p class="last">This method should only be called by resource providers that need to
obtain an extraction location, and only for names they intend to
extract, as it tracks the generated names for possible cleanup later.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">extraction_error()</span></code></dt>
<dd>Raise an <code class="docutils literal notranslate"><span class="pre">ExtractionError</span></code> describing the active exception as interfering
with the extraction process.  You should call this if you encounter any
OS errors extracting the file to the cache path; it will format the
operating system exception for you, and add other information to the
<code class="docutils literal notranslate"><span class="pre">ExtractionError</span></code> instance that may be needed by programs that want to
wrap or handle extraction errors themselves.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">postprocess(tempname,</span> <span class="pre">filename)</span></code></dt>
<dd><p class="first">Perform any platform-specific postprocessing of <cite>tempname</cite>.
Resource providers should call this method ONLY after successfully
extracting a compressed resource.  They must NOT call it on resources
that are already in the filesystem.</p>
<p class="last"><cite>tempname</cite> is the current (temporary) name of the file, and <cite>filename</cite>
is the name it will be renamed to by the caller after this routine
returns.</p>
</dd>
</dl>
</div>
</div>
<div class="section" id="metadata-api">
<h4><a class="toc-backref" href="#id27">Metadata API</a><a class="headerlink" href="#metadata-api" title="Permalink to this headline">¶</a></h4>
<p>The metadata API is used to access metadata resources bundled in a pluggable
distribution.  Metadata resources are virtual files or directories containing
information about the distribution, such as might be used by an extensible
application or framework to connect “plugins”.  Like other kinds of resources,
metadata resource names are <code class="docutils literal notranslate"><span class="pre">/</span></code>-separated and should not contain <code class="docutils literal notranslate"><span class="pre">..</span></code> or
begin with a <code class="docutils literal notranslate"><span class="pre">/</span></code>.  You should not use <code class="docutils literal notranslate"><span class="pre">os.path</span></code> routines to manipulate
resource paths.</p>
<p>The metadata API is provided by objects implementing the <code class="docutils literal notranslate"><span class="pre">IMetadataProvider</span></code>
or <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> interfaces.  <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects implement this
interface, as do objects returned by the <code class="docutils literal notranslate"><span class="pre">get_provider()</span></code> function:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">get_provider(package_or_requirement)</span></code></dt>
<dd><p class="first">If a package name is supplied, return an <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> for the
package.  If a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> is supplied, resolve it by returning a
<code class="docutils literal notranslate"><span class="pre">Distribution</span></code> from the current working set (searching the current
<code class="docutils literal notranslate"><span class="pre">Environment</span></code> if necessary and adding the newly found <code class="docutils literal notranslate"><span class="pre">Distribution</span></code>
to the working set).  If the named package can’t be imported, or the
<code class="docutils literal notranslate"><span class="pre">Requirement</span></code> can’t be satisfied, an exception is raised.</p>
<p class="last">NOTE: if you use a package name rather than a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code>, the object
you get back may not be a pluggable distribution, depending on the method
by which the package was installed.  In particular, “development” packages
and “single-version externally-managed” packages do not have any way to
map from a package name to the corresponding project’s metadata.  Do not
write code that passes a package name to <code class="docutils literal notranslate"><span class="pre">get_provider()</span></code> and then tries
to retrieve project metadata from the returned object.  It may appear to
work when the named package is in an <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file or directory, but
it will fail in other installation scenarios.  If you want project
metadata, you need to ask for a <em>project</em>, not a package.</p>
</dd>
</dl>
<div class="section" id="imetadataprovider-methods">
<h5><a class="toc-backref" href="#id28"><code class="docutils literal notranslate"><span class="pre">IMetadataProvider</span></code> Methods</a><a class="headerlink" href="#imetadataprovider-methods" title="Permalink to this headline">¶</a></h5>
<p>The methods provided by objects (such as <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> instances) that
implement the <code class="docutils literal notranslate"><span class="pre">IMetadataProvider</span></code> or <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> interfaces are:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">has_metadata(name)</span></code></dt>
<dd>Does the named metadata resource exist?</dd>
<dt><code class="docutils literal notranslate"><span class="pre">metadata_isdir(name)</span></code></dt>
<dd>Is the named metadata resource a directory?</dd>
<dt><code class="docutils literal notranslate"><span class="pre">metadata_listdir(name)</span></code></dt>
<dd>List of metadata names in the directory (like <code class="docutils literal notranslate"><span class="pre">os.listdir()</span></code>)</dd>
<dt><code class="docutils literal notranslate"><span class="pre">get_metadata(name)</span></code></dt>
<dd>Return the named metadata resource as a string.  The data is read in binary
mode; i.e., the exact bytes of the resource file are returned.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">get_metadata_lines(name)</span></code></dt>
<dd>Yield named metadata resource as list of non-blank non-comment lines.  This
is short for calling <code class="docutils literal notranslate"><span class="pre">yield_lines(provider.get_metadata(name))</span></code>.  See the
section on <a class="reference internal" href="#yield-lines">yield_lines()</a> below for more information on the syntax it
recognizes.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">run_script(script_name,</span> <span class="pre">namespace)</span></code></dt>
<dd>Execute the named script in the supplied namespace dictionary.  Raises
<code class="docutils literal notranslate"><span class="pre">ResolutionError</span></code> if there is no script by that name in the <code class="docutils literal notranslate"><span class="pre">scripts</span></code>
metadata directory.  <cite>namespace</cite> should be a Python dictionary, usually
a module dictionary if the script is being run as a module.</dd>
</dl>
</div>
</div>
<div class="section" id="exceptions">
<h4><a class="toc-backref" href="#id29">Exceptions</a><a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> provides a simple exception hierarchy for problems that may
occur when processing requests to locate and activate packages:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ResolutionError</span>
    <span class="n">DistributionNotFound</span>
    <span class="n">VersionConflict</span>
    <span class="n">UnknownExtra</span>

<span class="n">ExtractionError</span>
</pre></div>
</div>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">ResolutionError</span></code></dt>
<dd>This class is used as a base class for the other three exceptions, so that
you can catch all of them with a single “except” clause.  It is also raised
directly for miscellaneous requirement-resolution problems like trying to
run a script that doesn’t exist in the distribution it was requested from.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">DistributionNotFound</span></code></dt>
<dd>A distribution needed to fulfill a requirement could not be found.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">VersionConflict</span></code></dt>
<dd>The requested version of a project conflicts with an already-activated
version of the same project.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">UnknownExtra</span></code></dt>
<dd>One of the “extras” requested was not recognized by the distribution it
was requested from.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">ExtractionError</span></code></dt>
<dd><p class="first">A problem occurred extracting a resource to the Python Egg cache.  The
following attributes are available on instances of this exception:</p>
<dl class="last docutils">
<dt>manager</dt>
<dd>The resource manager that raised this exception</dd>
<dt>cache_path</dt>
<dd>The base directory for resource extraction</dd>
<dt>original_error</dt>
<dd>The exception instance that caused extraction to fail</dd>
</dl>
</dd>
</dl>
</div>
<div class="section" id="supporting-custom-importers">
<h4><a class="toc-backref" href="#id30">Supporting Custom Importers</a><a class="headerlink" href="#supporting-custom-importers" title="Permalink to this headline">¶</a></h4>
<p>By default, <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> supports normal filesystem imports, and
<code class="docutils literal notranslate"><span class="pre">zipimport</span></code> importers.  If you wish to use the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> features
with other (PEP 302-compatible) importers or module loaders, you may need to
register various handlers and support functions using these APIs:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">register_finder(importer_type,</span> <span class="pre">distribution_finder)</span></code></dt>
<dd><p class="first">Register <cite>distribution_finder</cite> to find distributions in <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> items.
<cite>importer_type</cite> is the type or class of a PEP 302 “Importer” (<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>
item handler), and <cite>distribution_finder</cite> is a callable that, when passed a
path item, the importer instance, and an <cite>only</cite> flag, yields
<code class="docutils literal notranslate"><span class="pre">Distribution</span></code> instances found under that path item.  (The <cite>only</cite> flag,
if true, means the finder should yield only <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects whose
<code class="docutils literal notranslate"><span class="pre">location</span></code> is equal to the path item provided.)</p>
<p class="last">See the source of the <code class="docutils literal notranslate"><span class="pre">pkg_resources.find_on_path</span></code> function for an
example finder function.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">register_loader_type(loader_type,</span> <span class="pre">provider_factory)</span></code></dt>
<dd>Register <cite>provider_factory</cite> to make <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> objects for
<cite>loader_type</cite>.  <cite>loader_type</cite> is the type or class of a PEP 302
<code class="docutils literal notranslate"><span class="pre">module.__loader__</span></code>, and <cite>provider_factory</cite> is a function that, when
passed a module object, returns an <a class="reference internal" href="#iresourceprovider">IResourceProvider</a> for that module,
allowing it to be used with the <a class="reference internal" href="#resourcemanager-api">ResourceManager API</a>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">register_namespace_handler(importer_type,</span> <span class="pre">namespace_handler)</span></code></dt>
<dd><p class="first">Register <cite>namespace_handler</cite> to declare namespace packages for the given
<cite>importer_type</cite>.  <cite>importer_type</cite> is the type or class of a PEP 302
“importer” (sys.path item handler), and <cite>namespace_handler</cite> is a callable
with a signature like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">namespace_handler</span><span class="p">(</span><span class="n">importer</span><span class="p">,</span> <span class="n">path_entry</span><span class="p">,</span> <span class="n">moduleName</span><span class="p">,</span> <span class="n">module</span><span class="p">):</span>
    <span class="c1"># return a path_entry to use for child packages</span>
</pre></div>
</div>
<p>Namespace handlers are only called if the relevant importer object has
already agreed that it can handle the relevant path item.  The handler
should only return a subpath if the module <code class="docutils literal notranslate"><span class="pre">__path__</span></code> does not already
contain an equivalent subpath.  Otherwise, it should return None.</p>
<p class="last">For an example namespace handler, see the source of the
<code class="docutils literal notranslate"><span class="pre">pkg_resources.file_ns_handler</span></code> function, which is used for both zipfile
importing and regular importing.</p>
</dd>
</dl>
<div class="section" id="iresourceprovider">
<h5><a class="toc-backref" href="#id31">IResourceProvider</a><a class="headerlink" href="#iresourceprovider" title="Permalink to this headline">¶</a></h5>
<p><code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> is an abstract class that documents what methods are
required of objects returned by a <cite>provider_factory</cite> registered with
<code class="docutils literal notranslate"><span class="pre">register_loader_type()</span></code>.  <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> is a subclass of
<code class="docutils literal notranslate"><span class="pre">IMetadataProvider</span></code>, so objects that implement this interface must also
implement all of the <a class="reference internal" href="#imetadataprovider-methods">IMetadataProvider Methods</a> as well as the methods
shown here.  The <cite>manager</cite> argument to the methods below must be an object
that supports the full <a class="reference internal" href="#resourcemanager-api">ResourceManager API</a> documented above.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">get_resource_filename(manager,</span> <span class="pre">resource_name)</span></code></dt>
<dd>Return a true filesystem path for <cite>resource_name</cite>, coordinating the
extraction with <cite>manager</cite>, if the resource must be unpacked to the
filesystem.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">get_resource_stream(manager,</span> <span class="pre">resource_name)</span></code></dt>
<dd>Return a readable file-like object for <cite>resource_name</cite>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">get_resource_string(manager,</span> <span class="pre">resource_name)</span></code></dt>
<dd>Return a string containing the contents of <cite>resource_name</cite>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">has_resource(resource_name)</span></code></dt>
<dd>Does the package contain the named resource?</dd>
<dt><code class="docutils literal notranslate"><span class="pre">resource_isdir(resource_name)</span></code></dt>
<dd>Is the named resource a directory?  Return a false value if the resource
does not exist or is not a directory.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">resource_listdir(resource_name)</span></code></dt>
<dd>Return a list of the contents of the resource directory, ala
<code class="docutils literal notranslate"><span class="pre">os.listdir()</span></code>.  Requesting the contents of a non-existent directory may
raise an exception.</dd>
</dl>
<p>Note, by the way, that your provider classes need not (and should not) subclass
<code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> or <code class="docutils literal notranslate"><span class="pre">IMetadataProvider</span></code>!  These classes exist solely
for documentation purposes and do not provide any useful implementation code.
You may instead wish to subclass one of the <a class="reference internal" href="#built-in-resource-providers">built-in resource providers</a>.</p>
</div>
<div class="section" id="built-in-resource-providers">
<h5><a class="toc-backref" href="#id32">Built-in Resource Providers</a><a class="headerlink" href="#built-in-resource-providers" title="Permalink to this headline">¶</a></h5>
<p><code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> includes several provider classes that are automatically used
where appropriate.  Their inheritance tree looks like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">NullProvider</span>
    <span class="n">EggProvider</span>
        <span class="n">DefaultProvider</span>
            <span class="n">PathMetadata</span>
        <span class="n">ZipProvider</span>
            <span class="n">EggMetadata</span>
    <span class="n">EmptyProvider</span>
        <span class="n">FileMetadata</span>
</pre></div>
</div>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">NullProvider</span></code></dt>
<dd>This provider class is just an abstract base that provides for common
provider behaviors (such as running scripts), given a definition for just
a few abstract methods.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">EggProvider</span></code></dt>
<dd>This provider class adds in some egg-specific features that are common
to zipped and unzipped eggs.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">DefaultProvider</span></code></dt>
<dd>This provider class is used for unpacked eggs and “plain old Python”
filesystem modules.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">ZipProvider</span></code></dt>
<dd>This provider class is used for all zipped modules, whether they are eggs
or not.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">EmptyProvider</span></code></dt>
<dd>This provider class always returns answers consistent with a provider that
has no metadata or resources.  <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects created without
a <code class="docutils literal notranslate"><span class="pre">metadata</span></code> argument use an instance of this provider class instead.
Since all <code class="docutils literal notranslate"><span class="pre">EmptyProvider</span></code> instances are equivalent, there is no need
to have more than one instance.  <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> therefore creates a
global instance of this class under the name <code class="docutils literal notranslate"><span class="pre">empty_provider</span></code>, and you
may use it if you have need of an <code class="docutils literal notranslate"><span class="pre">EmptyProvider</span></code> instance.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">PathMetadata(path,</span> <span class="pre">egg_info)</span></code></dt>
<dd>Create an <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> for a filesystem-based distribution, where
<cite>path</cite> is the filesystem location of the importable modules, and <cite>egg_info</cite>
is the filesystem location of the distribution’s metadata directory.
<cite>egg_info</cite> should usually be the <code class="docutils literal notranslate"><span class="pre">EGG-INFO</span></code> subdirectory of <cite>path</cite> for an
“unpacked egg”, and a <code class="docutils literal notranslate"><span class="pre">ProjectName.egg-info</span></code> subdirectory of <cite>path</cite> for
a “development egg”.  However, other uses are possible for custom purposes.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">EggMetadata(zipimporter)</span></code></dt>
<dd>Create an <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> for a zipfile-based distribution.  The
<cite>zipimporter</cite> should be a <code class="docutils literal notranslate"><span class="pre">zipimport.zipimporter</span></code> instance, and may
represent a “basket” (a zipfile containing multiple “.egg” subdirectories)
a specific egg <em>within</em> a basket, or a zipfile egg (where the zipfile
itself is a “.egg”).  It can also be a combination, such as a zipfile egg
that also contains other eggs.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">FileMetadata(path_to_pkg_info)</span></code></dt>
<dd>Create an <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> that provides exactly one metadata
resource: <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code>.  The supplied path should be a distutils PKG-INFO
file.  This is basically the same as an <code class="docutils literal notranslate"><span class="pre">EmptyProvider</span></code>, except that
requests for <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> will be answered using the contents of the
designated file.  (This provider is used to wrap <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> files
installed by vendor-supplied system packages.)</dd>
</dl>
</div>
</div>
<div class="section" id="utility-functions">
<h4><a class="toc-backref" href="#id33">Utility Functions</a><a class="headerlink" href="#utility-functions" title="Permalink to this headline">¶</a></h4>
<p>In addition to its high-level APIs, <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> also includes several
generally-useful utility routines.  These routines are used to implement the
high-level APIs, but can also be quite useful by themselves.</p>
<div class="section" id="parsing-utilities">
<h5><a class="toc-backref" href="#id34">Parsing Utilities</a><a class="headerlink" href="#parsing-utilities" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">parse_version(version)</span></code></dt>
<dd>Parsed a project’s version string as defined by PEP 440. The returned
value will be an object that represents the version. These objects may
be compared to each other and sorted. The sorting algorithm is as defined
by PEP 440 with the addition that any version which is not a valid PEP 440
version will be considered less than any valid PEP 440 version and the
invalid versions will continue sorting using the original algorithm.</dd>
</dl>
<dl class="docutils" id="yield-lines">
<dt><code class="docutils literal notranslate"><span class="pre">yield_lines(strs)</span></code></dt>
<dd><p class="first">Yield non-empty/non-comment lines from a string/unicode or a possibly-
nested sequence thereof.  If <cite>strs</cite> is an instance of <code class="docutils literal notranslate"><span class="pre">basestring</span></code>, it
is split into lines, and each non-blank, non-comment line is yielded after
stripping leading and trailing whitespace.  (Lines whose first non-blank
character is <code class="docutils literal notranslate"><span class="pre">#</span></code> are considered comment lines.)</p>
<p>If <cite>strs</cite> is not an instance of <code class="docutils literal notranslate"><span class="pre">basestring</span></code>, it is iterated over, and
each item is passed recursively to <code class="docutils literal notranslate"><span class="pre">yield_lines()</span></code>, so that an arbitrarily
nested sequence of strings, or sequences of sequences of strings can be
flattened out to the lines contained therein.  So for example, passing
a file object or a list of strings to <code class="docutils literal notranslate"><span class="pre">yield_lines</span></code> will both work.
(Note that between each string in a sequence of strings there is assumed to
be an implicit line break, so lines cannot bridge two strings in a
sequence.)</p>
<p class="last">This routine is used extensively by <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> to parse metadata
and file formats of various kinds, and most other <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>
parsing functions that yield multiple values will use it to break up their
input.  However, this routine is idempotent, so calling <code class="docutils literal notranslate"><span class="pre">yield_lines()</span></code>
on the output of another call to <code class="docutils literal notranslate"><span class="pre">yield_lines()</span></code> is completely harmless.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">split_sections(strs)</span></code></dt>
<dd><p class="first">Split a string (or possibly-nested iterable thereof), yielding <code class="docutils literal notranslate"><span class="pre">(section,</span>
<span class="pre">content)</span></code> pairs found using an <code class="docutils literal notranslate"><span class="pre">.ini</span></code>-like syntax.  Each <code class="docutils literal notranslate"><span class="pre">section</span></code> is
a whitespace-stripped version of the section name (“<code class="docutils literal notranslate"><span class="pre">[section]</span></code>”)
and each <code class="docutils literal notranslate"><span class="pre">content</span></code> is a list of stripped lines excluding blank lines and
comment-only lines.  If there are any non-blank, non-comment lines before
the first section header, they’re yielded in a first <code class="docutils literal notranslate"><span class="pre">section</span></code> of
<code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<p>This routine uses <code class="docutils literal notranslate"><span class="pre">yield_lines()</span></code> as its front end, so you can pass in
anything that <code class="docutils literal notranslate"><span class="pre">yield_lines()</span></code> accepts, such as an open text file, string,
or sequence of strings.  <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> is raised if a malformed section
header is found (i.e. a line starting with <code class="docutils literal notranslate"><span class="pre">[</span></code> but not ending with
<code class="docutils literal notranslate"><span class="pre">]</span></code>).</p>
<p class="last">Note that this simplistic parser assumes that any line whose first nonblank
character is <code class="docutils literal notranslate"><span class="pre">[</span></code> is a section heading, so it can’t support .ini format
variations that allow <code class="docutils literal notranslate"><span class="pre">[</span></code> as the first nonblank character on other lines.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">safe_name(name)</span></code></dt>
<dd>Return a “safe” form of a project’s name, suitable for use in a
<code class="docutils literal notranslate"><span class="pre">Requirement</span></code> string, as a distribution name, or a PyPI project name.
All non-alphanumeric runs are condensed to single “-” characters, such that
a name like “The $$$ Tree” becomes “The-Tree”.  Note that if you are
generating a filename from this value you should combine it with a call to
<code class="docutils literal notranslate"><span class="pre">to_filename()</span></code> so all dashes (“-“) are replaced by underscores (“_”).
See <code class="docutils literal notranslate"><span class="pre">to_filename()</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">safe_version(version)</span></code></dt>
<dd>This will return the normalized form of any PEP 440 version, if the version
string is not PEP 440 compatible than it is similar to <code class="docutils literal notranslate"><span class="pre">safe_name()</span></code>
except that spaces in the input become dots, and dots are allowed to exist
in the output.  As with <code class="docutils literal notranslate"><span class="pre">safe_name()</span></code>, if you are generating a filename
from this you should replace any “-” characters in the output with
underscores.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">safe_extra(extra)</span></code></dt>
<dd>Return a “safe” form of an extra’s name, suitable for use in a requirement
string or a setup script’s <code class="docutils literal notranslate"><span class="pre">extras_require</span></code> keyword.  This routine is
similar to <code class="docutils literal notranslate"><span class="pre">safe_name()</span></code> except that non-alphanumeric runs are replaced
by a single underbar (<code class="docutils literal notranslate"><span class="pre">_</span></code>), and the result is lowercased.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">to_filename(name_or_version)</span></code></dt>
<dd>Escape a name or version string so it can be used in a dash-separated
filename (or <code class="docutils literal notranslate"><span class="pre">#egg=name-version</span></code> tag) without ambiguity.  You
should only pass in values that were returned by <code class="docutils literal notranslate"><span class="pre">safe_name()</span></code> or
<code class="docutils literal notranslate"><span class="pre">safe_version()</span></code>.</dd>
</dl>
</div>
<div class="section" id="platform-utilities">
<h5><a class="toc-backref" href="#id35">Platform Utilities</a><a class="headerlink" href="#platform-utilities" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">get_build_platform()</span></code></dt>
<dd>Return this platform’s identifier string.  For Windows, the return value
is <code class="docutils literal notranslate"><span class="pre">&quot;win32&quot;</span></code>, and for macOS it is a string of the form
<code class="docutils literal notranslate"><span class="pre">&quot;macosx-10.4-ppc&quot;</span></code>.  All other platforms return the same uname-based
string that the <code class="docutils literal notranslate"><span class="pre">distutils.util.get_platform()</span></code> function returns.
This string is the minimum platform version required by distributions built
on the local machine.  (Backward compatibility note: setuptools versions
prior to 0.6b1 called this function <code class="docutils literal notranslate"><span class="pre">get_platform()</span></code>, and the function is
still available under that name for backward compatibility reasons.)</dd>
<dt><code class="docutils literal notranslate"><span class="pre">get_supported_platform()</span></code> (New in 0.6b1)</dt>
<dd>This is the similar to <code class="docutils literal notranslate"><span class="pre">get_build_platform()</span></code>, but is the maximum
platform version that the local machine supports.  You will usually want
to use this value as the <code class="docutils literal notranslate"><span class="pre">provided</span></code> argument to the
<code class="docutils literal notranslate"><span class="pre">compatible_platforms()</span></code> function.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">compatible_platforms(provided,</span> <span class="pre">required)</span></code></dt>
<dd>Return true if a distribution built on the <cite>provided</cite> platform may be used
on the <cite>required</cite> platform.  If either platform value is <code class="docutils literal notranslate"><span class="pre">None</span></code>, it is
considered a wildcard, and the platforms are therefore compatible.
Likewise, if the platform strings are equal, they’re also considered
compatible, and <code class="docutils literal notranslate"><span class="pre">True</span></code> is returned.  Currently, the only non-equal
platform strings that are considered compatible are macOS platform
strings with the same hardware type (e.g. <code class="docutils literal notranslate"><span class="pre">ppc</span></code>) and major version
(e.g. <code class="docutils literal notranslate"><span class="pre">10</span></code>) with the <cite>provided</cite> platform’s minor version being less than
or equal to the <cite>required</cite> platform’s minor version.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">get_default_cache()</span></code></dt>
<dd>Determine the default cache location for extracting resources from zipped
eggs.  This routine returns the <code class="docutils literal notranslate"><span class="pre">PYTHON_EGG_CACHE</span></code> environment variable,
if set.  Otherwise, on Windows, it returns a “Python-Eggs” subdirectory of
the user’s “Application Data” directory.  On all other systems, it returns
<code class="docutils literal notranslate"><span class="pre">os.path.expanduser(&quot;~/.python-eggs&quot;)</span></code> if <code class="docutils literal notranslate"><span class="pre">PYTHON_EGG_CACHE</span></code> is not
set.</dd>
</dl>
</div>
<div class="section" id="pep-302-utilities">
<h5><a class="toc-backref" href="#id36">PEP 302 Utilities</a><a class="headerlink" href="#pep-302-utilities" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">get_importer(path_item)</span></code></dt>
<dd>A deprecated alias for <code class="docutils literal notranslate"><span class="pre">pkgutil.get_importer()</span></code></dd>
</dl>
</div>
<div class="section" id="file-path-utilities">
<h5><a class="toc-backref" href="#id37">File/Path Utilities</a><a class="headerlink" href="#file-path-utilities" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">ensure_directory(path)</span></code></dt>
<dd>Ensure that the parent directory (<code class="docutils literal notranslate"><span class="pre">os.path.dirname</span></code>) of <cite>path</cite> actually
exists, using <code class="docutils literal notranslate"><span class="pre">os.makedirs()</span></code> if necessary.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">normalize_path(path)</span></code></dt>
<dd>Return a “normalized” version of <cite>path</cite>, such that two paths represent
the same filesystem location if they have equal <code class="docutils literal notranslate"><span class="pre">normalized_path()</span></code>
values.  Specifically, this is a shortcut for calling <code class="docutils literal notranslate"><span class="pre">os.path.realpath</span></code>
and <code class="docutils literal notranslate"><span class="pre">os.path.normcase</span></code> on <cite>path</cite>.  Unfortunately, on certain platforms
(notably Cygwin and macOS) the <code class="docutils literal notranslate"><span class="pre">normcase</span></code> function does not accurately
reflect the platform’s case-sensitivity, so there is always the possibility
of two apparently-different paths being equal on such platforms.</dd>
</dl>
</div>
<div class="section" id="history">
<h5><a class="toc-backref" href="#id38">History</a><a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h5>
<dl class="docutils">
<dt>0.6c9</dt>
<dd><ul class="first last simple">
<li>Fix <code class="docutils literal notranslate"><span class="pre">resource_listdir('')</span></code> always returning an empty list for zipped eggs.</li>
</ul>
</dd>
<dt>0.6c7</dt>
<dd><ul class="first last simple">
<li>Fix package precedence problem where single-version eggs installed in
<code class="docutils literal notranslate"><span class="pre">site-packages</span></code> would take precedence over <code class="docutils literal notranslate"><span class="pre">.egg</span></code> files (or directories)
installed in <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>.</li>
</ul>
</dd>
<dt>0.6c6</dt>
<dd><ul class="first last simple">
<li>Fix extracted C extensions not having executable permissions under Cygwin.</li>
<li>Allow <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> files to contain relative paths.</li>
<li>Fix cache dir defaults on Windows when multiple environment vars are needed
to construct a path.</li>
</ul>
</dd>
<dt>0.6c4</dt>
<dd><ul class="first last simple">
<li>Fix “dev” versions being considered newer than release candidates.</li>
</ul>
</dd>
<dt>0.6c3</dt>
<dd><ul class="first last simple">
<li>Python 2.5 compatibility fixes.</li>
</ul>
</dd>
<dt>0.6c2</dt>
<dd><ul class="first last simple">
<li>Fix a problem with eggs specified directly on <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> on
case-insensitive filesystems possibly not showing up in the default
working set, due to differing normalizations of <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> entries.</li>
</ul>
</dd>
<dt>0.6b3</dt>
<dd><ul class="first last simple">
<li>Fixed a duplicate path insertion problem on case-insensitive filesystems.</li>
</ul>
</dd>
<dt>0.6b1</dt>
<dd><ul class="first last simple">
<li>Split <code class="docutils literal notranslate"><span class="pre">get_platform()</span></code> into <code class="docutils literal notranslate"><span class="pre">get_supported_platform()</span></code> and
<code class="docutils literal notranslate"><span class="pre">get_build_platform()</span></code> to work around a Mac versioning problem that caused
the behavior of <code class="docutils literal notranslate"><span class="pre">compatible_platforms()</span></code> to be platform specific.</li>
<li>Fix entry point parsing when a standalone module name has whitespace
between it and the extras.</li>
</ul>
</dd>
<dt>0.6a11</dt>
<dd><ul class="first last simple">
<li>Added <code class="docutils literal notranslate"><span class="pre">ExtractionError</span></code> and <code class="docutils literal notranslate"><span class="pre">ResourceManager.extraction_error()</span></code> so that
cache permission problems get a more user-friendly explanation of the
problem, and so that programs can catch and handle extraction errors if they
need to.</li>
</ul>
</dd>
<dt>0.6a10</dt>
<dd><ul class="first last simple">
<li>Added the <code class="docutils literal notranslate"><span class="pre">extras</span></code> attribute to <code class="docutils literal notranslate"><span class="pre">Distribution</span></code>, the <code class="docutils literal notranslate"><span class="pre">find_plugins()</span></code>
method to <code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code>, and the <code class="docutils literal notranslate"><span class="pre">__add__()</span></code> and <code class="docutils literal notranslate"><span class="pre">__iadd__()</span></code> methods
to <code class="docutils literal notranslate"><span class="pre">Environment</span></code>.</li>
<li><code class="docutils literal notranslate"><span class="pre">safe_name()</span></code> now allows dots in project names.</li>
<li>There is a new <code class="docutils literal notranslate"><span class="pre">to_filename()</span></code> function that escapes project names and
versions for safe use in constructing egg filenames from a Distribution
object’s metadata.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">Distribution.clone()</span></code> method, and keyword argument support to other
<code class="docutils literal notranslate"><span class="pre">Distribution</span></code> constructors.</li>
<li>Added the <code class="docutils literal notranslate"><span class="pre">DEVELOP_DIST</span></code> precedence, and automatically assign it to
eggs using <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> format.</li>
</ul>
</dd>
<dt>0.6a9</dt>
<dd><ul class="first last simple">
<li>Don’t raise an error when an invalid (unfinished) distribution is found
unless absolutely necessary.  Warn about skipping invalid/unfinished eggs
when building an Environment.</li>
<li>Added support for <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> files or directories with version/platform
information embedded in the filename, so that system packagers have the
option of including <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> files to indicate the presence of a
system-installed egg, without needing to use <code class="docutils literal notranslate"><span class="pre">.egg</span></code> directories, zipfiles,
or <code class="docutils literal notranslate"><span class="pre">.pth</span></code> manipulation.</li>
<li>Changed <code class="docutils literal notranslate"><span class="pre">parse_version()</span></code> to remove dashes before pre-release tags, so
that <code class="docutils literal notranslate"><span class="pre">0.2-rc1</span></code> is considered an <em>older</em> version than <code class="docutils literal notranslate"><span class="pre">0.2</span></code>, and is equal
to <code class="docutils literal notranslate"><span class="pre">0.2rc1</span></code>.  The idea that a dash <em>always</em> meant a post-release version
was highly non-intuitive to setuptools users and Python developers, who
seem to want to use <code class="docutils literal notranslate"><span class="pre">-rc</span></code> version numbers a lot.</li>
</ul>
</dd>
<dt>0.6a8</dt>
<dd><ul class="first last simple">
<li>Fixed a problem with <code class="docutils literal notranslate"><span class="pre">WorkingSet.resolve()</span></code> that prevented version
conflicts from being detected at runtime.</li>
<li>Improved runtime conflict warning message to identify a line in the user’s
program, rather than flagging the <code class="docutils literal notranslate"><span class="pre">warn()</span></code> call in <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>.</li>
<li>Avoid giving runtime conflict warnings for namespace packages, even if they
were declared by a different package than the one currently being activated.</li>
<li>Fix path insertion algorithm for case-insensitive filesystems.</li>
<li>Fixed a problem with nested namespace packages (e.g. <code class="docutils literal notranslate"><span class="pre">peak.util</span></code>) not
being set as an attribute of their parent package.</li>
</ul>
</dd>
<dt>0.6a6</dt>
<dd><ul class="first last simple">
<li>Activated distributions are now inserted in <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> (and the working
set) just before the directory that contains them, instead of at the end.
This allows e.g. eggs in <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> to override unmanaged modules in
the same location, and allows eggs found earlier on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> to override
ones found later.</li>
<li>When a distribution is activated, it now checks whether any contained
non-namespace modules have already been imported and issues a warning if
a conflicting module has already been imported.</li>
<li>Changed dependency processing so that it’s breadth-first, allowing a
depender’s preferences to override those of a dependee, to prevent conflicts
when a lower version is acceptable to the dependee, but not the depender.</li>
<li>Fixed a problem extracting zipped files on Windows, when the egg in question
has had changed contents but still has the same version number.</li>
</ul>
</dd>
<dt>0.6a4</dt>
<dd><ul class="first last simple">
<li>Fix a bug in <code class="docutils literal notranslate"><span class="pre">WorkingSet.resolve()</span></code> that was introduced in 0.6a3.</li>
</ul>
</dd>
<dt>0.6a3</dt>
<dd><ul class="first last simple">
<li>Added <code class="docutils literal notranslate"><span class="pre">safe_extra()</span></code> parsing utility routine, and use it for Requirement,
EntryPoint, and Distribution objects’ extras handling.</li>
</ul>
</dd>
<dt>0.6a1</dt>
<dd><ul class="first last simple">
<li>Enhanced performance of <code class="docutils literal notranslate"><span class="pre">require()</span></code> and related operations when all
requirements are already in the working set, and enhanced performance of
directory scanning for distributions.</li>
<li>Fixed some problems using <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> w/PEP 302 loaders other than
<code class="docutils literal notranslate"><span class="pre">zipimport</span></code>, and the previously-broken “eager resource” support.</li>
<li>Fixed <code class="docutils literal notranslate"><span class="pre">pkg_resources.resource_exists()</span></code> not working correctly, along with
some other resource API bugs.</li>
<li>Many API changes and enhancements:<ul>
<li>Added <code class="docutils literal notranslate"><span class="pre">EntryPoint</span></code>, <code class="docutils literal notranslate"><span class="pre">get_entry_map</span></code>, <code class="docutils literal notranslate"><span class="pre">load_entry_point</span></code>, and
<code class="docutils literal notranslate"><span class="pre">get_entry_info</span></code> APIs for dynamic plugin discovery.</li>
<li><code class="docutils literal notranslate"><span class="pre">list_resources</span></code> is now <code class="docutils literal notranslate"><span class="pre">resource_listdir</span></code> (and it actually works)</li>
<li>Resource API functions like <code class="docutils literal notranslate"><span class="pre">resource_string()</span></code> that accepted a package
name and resource name, will now also accept a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> object in
place of the package name (to allow access to non-package data files in
an egg).</li>
<li><code class="docutils literal notranslate"><span class="pre">get_provider()</span></code> will now accept a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> instance or a module
name.  If it is given a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code>, it will return a corresponding
<code class="docutils literal notranslate"><span class="pre">Distribution</span></code> (by calling <code class="docutils literal notranslate"><span class="pre">require()</span></code> if a suitable distribution
isn’t already in the working set), rather than returning a metadata and
resource provider for a specific module.  (The difference is in how
resource paths are interpreted; supplying a module name means resources
path will be module-relative, rather than relative to the distribution’s
root.)</li>
<li><code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects now implement the <code class="docutils literal notranslate"><span class="pre">IResourceProvider</span></code> and
<code class="docutils literal notranslate"><span class="pre">IMetadataProvider</span></code> interfaces, so you don’t need to reference the (no
longer available) <code class="docutils literal notranslate"><span class="pre">metadata</span></code> attribute to get at these interfaces.</li>
<li><code class="docutils literal notranslate"><span class="pre">Distribution</span></code> and <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> both have a <code class="docutils literal notranslate"><span class="pre">project_name</span></code>
attribute for the project name they refer to.  (Previously these were
<code class="docutils literal notranslate"><span class="pre">name</span></code> and <code class="docutils literal notranslate"><span class="pre">distname</span></code> attributes.)</li>
<li>The <code class="docutils literal notranslate"><span class="pre">path</span></code> attribute of <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects is now <code class="docutils literal notranslate"><span class="pre">location</span></code>,
because it isn’t necessarily a filesystem path (and hasn’t been for some
time now).  The <code class="docutils literal notranslate"><span class="pre">location</span></code> of <code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects in the filesystem
should always be normalized using <code class="docutils literal notranslate"><span class="pre">pkg_resources.normalize_path()</span></code>; all
of the setuptools’ code that generates distributions from the filesystem
(including <code class="docutils literal notranslate"><span class="pre">Distribution.from_filename()</span></code>) ensure this invariant, but if
you use a more generic API like <code class="docutils literal notranslate"><span class="pre">Distribution()</span></code> or
<code class="docutils literal notranslate"><span class="pre">Distribution.from_location()</span></code> you should take care that you don’t
create a distribution with an un-normalized filesystem path.</li>
<li><code class="docutils literal notranslate"><span class="pre">Distribution</span></code> objects now have an <code class="docutils literal notranslate"><span class="pre">as_requirement()</span></code> method that
returns a <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> for the distribution’s project name and version.</li>
<li>Distribution objects no longer have an <code class="docutils literal notranslate"><span class="pre">installed_on()</span></code> method, and the
<code class="docutils literal notranslate"><span class="pre">install_on()</span></code> method is now <code class="docutils literal notranslate"><span class="pre">activate()</span></code> (but may go away altogether
soon).  The <code class="docutils literal notranslate"><span class="pre">depends()</span></code> method has also been renamed to <code class="docutils literal notranslate"><span class="pre">requires()</span></code>,
and <code class="docutils literal notranslate"><span class="pre">InvalidOption</span></code> is now <code class="docutils literal notranslate"><span class="pre">UnknownExtra</span></code>.</li>
<li><code class="docutils literal notranslate"><span class="pre">find_distributions()</span></code> now takes an additional argument called <code class="docutils literal notranslate"><span class="pre">only</span></code>,
that tells it to only yield distributions whose location is the passed-in
path.  (It defaults to False, so that the default behavior is unchanged.)</li>
<li><code class="docutils literal notranslate"><span class="pre">AvailableDistributions</span></code> is now called <code class="docutils literal notranslate"><span class="pre">Environment</span></code>, and the
<code class="docutils literal notranslate"><span class="pre">get()</span></code>, <code class="docutils literal notranslate"><span class="pre">__len__()</span></code>, and <code class="docutils literal notranslate"><span class="pre">__contains__()</span></code> methods were removed,
because they weren’t particularly useful.  <code class="docutils literal notranslate"><span class="pre">__getitem__()</span></code> no longer
raises <code class="docutils literal notranslate"><span class="pre">KeyError</span></code>; it just returns an empty list if there are no
distributions for the named project.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">resolve()</span></code> method of <code class="docutils literal notranslate"><span class="pre">Environment</span></code> is now a method of
<code class="docutils literal notranslate"><span class="pre">WorkingSet</span></code> instead, and the <code class="docutils literal notranslate"><span class="pre">best_match()</span></code> method now uses a working
set instead of a path list as its second argument.</li>
<li>There is a new <code class="docutils literal notranslate"><span class="pre">pkg_resources.add_activation_listener()</span></code> API that lets
you register a callback for notifications about distributions added to
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> (including the distributions already on it).  This is
basically a hook for extensible applications and frameworks to be able to
search for plugin metadata in distributions added at runtime.</li>
</ul>
</li>
</ul>
</dd>
<dt>0.5a13</dt>
<dd><ul class="first last simple">
<li>Fixed a bug in resource extraction from nested packages in a zipped egg.</li>
</ul>
</dd>
<dt>0.5a12</dt>
<dd><ul class="first last simple">
<li>Updated extraction/cache mechanism for zipped resources to avoid inter-
process and inter-thread races during extraction.  The default cache
location can now be set via the <code class="docutils literal notranslate"><span class="pre">PYTHON_EGGS_CACHE</span></code> environment variable,
and the default Windows cache is now a <code class="docutils literal notranslate"><span class="pre">Python-Eggs</span></code> subdirectory of the
current user’s “Application Data” directory, if the <code class="docutils literal notranslate"><span class="pre">PYTHON_EGGS_CACHE</span></code>
variable isn’t set.</li>
</ul>
</dd>
<dt>0.5a10</dt>
<dd><ul class="first last simple">
<li>Fix a problem with <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> being confused by non-existent eggs on
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> (e.g. if a user deletes an egg without removing it from the
<code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> file).</li>
<li>Fix a problem with “basket” support in <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>, where egg-finding
never actually went inside <code class="docutils literal notranslate"><span class="pre">.egg</span></code> files.</li>
<li>Made <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> import the module you request resources from, if it’s
not already imported.</li>
</ul>
</dd>
<dt>0.5a4</dt>
<dd><ul class="first last simple">
<li><code class="docutils literal notranslate"><span class="pre">pkg_resources.AvailableDistributions.resolve()</span></code> and related methods now
accept an <code class="docutils literal notranslate"><span class="pre">installer</span></code> argument: a callable taking one argument, a
<code class="docutils literal notranslate"><span class="pre">Requirement</span></code> instance.  The callable must return a <code class="docutils literal notranslate"><span class="pre">Distribution</span></code>
object, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if no distribution is found.  This feature is used by
EasyInstall to resolve dependencies by recursively invoking itself.</li>
</ul>
</dd>
<dt>0.4a4</dt>
<dd><ul class="first last simple">
<li>Fix problems with <code class="docutils literal notranslate"><span class="pre">resource_listdir()</span></code>, <code class="docutils literal notranslate"><span class="pre">resource_isdir()</span></code> and resource
directory extraction for zipped eggs.</li>
</ul>
</dd>
<dt>0.4a3</dt>
<dd><ul class="first last simple">
<li>Fixed scripts not being able to see a <code class="docutils literal notranslate"><span class="pre">__file__</span></code> variable in <code class="docutils literal notranslate"><span class="pre">__main__</span></code></li>
<li>Fixed a problem with <code class="docutils literal notranslate"><span class="pre">resource_isdir()</span></code> implementation that was introduced
in 0.4a2.</li>
</ul>
</dd>
<dt>0.4a1</dt>
<dd><ul class="first last simple">
<li>Fixed a bug in requirements processing for exact versions (i.e. <code class="docutils literal notranslate"><span class="pre">==</span></code> and
<code class="docutils literal notranslate"><span class="pre">!=</span></code>) when only one condition was included.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">safe_name()</span></code> and <code class="docutils literal notranslate"><span class="pre">safe_version()</span></code> APIs to clean up handling of
arbitrary distribution names and versions found on PyPI.</li>
</ul>
</dd>
<dt>0.3a4</dt>
<dd><ul class="first last simple">
<li><code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> now supports resource directories, not just the resources
in them.  In particular, there are <code class="docutils literal notranslate"><span class="pre">resource_listdir()</span></code> and
<code class="docutils literal notranslate"><span class="pre">resource_isdir()</span></code> APIs.</li>
<li><code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> now supports “egg baskets” – .egg zipfiles which contain
multiple distributions in subdirectories whose names end with <code class="docutils literal notranslate"><span class="pre">.egg</span></code>.
Having such a “basket” in a directory on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> is equivalent to
having the individual eggs in that directory, but the contained eggs can
be individually added (or not) to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.  Currently, however, there
is no automated way to create baskets.</li>
<li>Namespace package manipulation is now protected by the Python import lock.</li>
</ul>
</dd>
<dt>0.3a1</dt>
<dd><ul class="first last simple">
<li>Initial release.</li>
</ul>
</dd>
</dl>
</div>
</div>
</div>
</div>
<span id="document-python3"></span><div class="section" id="supporting-both-python-2-and-python-3-with-setuptools">
<h2>Supporting both Python 2 and Python 3 with Setuptools<a class="headerlink" href="#supporting-both-python-2-and-python-3-with-setuptools" title="Permalink to this headline">¶</a></h2>
<p>Starting with Distribute version 0.6.2 and Setuptools 0.7, the Setuptools
project supported Python 3. Installing and
using setuptools for Python 3 code works exactly the same as for Python 2
code.</p>
<p>Setuptools provides a facility to invoke 2to3 on the code as a part of the
build process, by setting the keyword parameter <code class="docutils literal notranslate"><span class="pre">use_2to3</span></code> to True, but
the Setuptools project strongly recommends instead developing a unified codebase
using <a class="reference external" href="https://pypi.org/project/six/">six</a>,
<a class="reference external" href="https://pypi.org/project/future/">future</a>, or another compatibility
library.</p>
<div class="section" id="using-2to3">
<h3>Using 2to3<a class="headerlink" href="#using-2to3" title="Permalink to this headline">¶</a></h3>
<p>Setuptools attempts to make the porting process easier by automatically
running
2to3 as a part of running tests. To do so, you need to configure the
setup.py so that you can run the unit tests with <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">test</span></code>.</p>
<p>See <a class="reference internal" href="index.html#test"><span class="std std-ref">test - Build package and run a unittest suite</span></a> for more information on this.</p>
<p>Once you have the tests running under Python 2, you can add the use_2to3
keyword parameters to setup(), and start running the tests under Python 3.
The test command will now first run the build command during which the code
will be converted with 2to3, and the tests will then be run from the build
directory, as opposed from the source directory as is normally done.</p>
<p>Setuptools will convert all Python files, and also all doctests in Python
files. However, if you have doctests located in separate text files, these
will not automatically be converted. By adding them to the
<code class="docutils literal notranslate"><span class="pre">convert_2to3_doctests</span></code> keyword parameter Setuptools will convert them as
well.</p>
<p>By default, the conversion uses all fixers in the <code class="docutils literal notranslate"><span class="pre">lib2to3.fixers</span></code> package.
To use additional fixers, the parameter <code class="docutils literal notranslate"><span class="pre">use_2to3_fixers</span></code> can be set
to a list of names of packages containing fixers. To exclude fixers, the
parameter <code class="docutils literal notranslate"><span class="pre">use_2to3_exclude_fixers</span></code> can be set to fixer names to be
skipped.</p>
<p>An example setup.py might look something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span>

<span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s1">&#39;your.module&#39;</span><span class="p">,</span>
    <span class="n">version</span><span class="o">=</span><span class="s1">&#39;1.0&#39;</span><span class="p">,</span>
    <span class="n">description</span><span class="o">=</span><span class="s1">&#39;This is your awesome module&#39;</span><span class="p">,</span>
    <span class="n">author</span><span class="o">=</span><span class="s1">&#39;You&#39;</span><span class="p">,</span>
    <span class="n">author_email</span><span class="o">=</span><span class="s1">&#39;your@email&#39;</span><span class="p">,</span>
    <span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;&#39;</span><span class="p">:</span> <span class="s1">&#39;src&#39;</span><span class="p">},</span>
    <span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;your&#39;</span><span class="p">,</span> <span class="s1">&#39;you.module&#39;</span><span class="p">],</span>
    <span class="n">test_suite</span><span class="o">=</span><span class="s1">&#39;your.module.tests&#39;</span><span class="p">,</span>
    <span class="n">use_2to3</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
    <span class="n">convert_2to3_doctests</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;src/your/module/README.txt&#39;</span><span class="p">],</span>
    <span class="n">use_2to3_fixers</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;your.fixers&#39;</span><span class="p">],</span>
    <span class="n">use_2to3_exclude_fixers</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;lib2to3.fixes.fix_import&#39;</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<div class="section" id="differential-conversion">
<h4>Differential conversion<a class="headerlink" href="#differential-conversion" title="Permalink to this headline">¶</a></h4>
<p>Note that a file will only be copied and converted during the build process
if the source file has been changed. If you add a file to the doctests
that should be converted, it will not be converted the next time you run
the tests, since it hasn’t been modified. You need to remove it from the
build directory. Also if you run the build, install or test commands before
adding the use_2to3 parameter, you will have to remove the build directory
before you run the test command, as the files otherwise will seem updated,
and no conversion will happen.</p>
<p>In general, if code doesn’t seem to be converted, deleting the build directory
and trying again is a good safeguard against the build directory getting
“out of sync” with the source directory.</p>
</div>
</div>
<div class="section" id="distributing-python-3-modules">
<h3>Distributing Python 3 modules<a class="headerlink" href="#distributing-python-3-modules" title="Permalink to this headline">¶</a></h3>
<p>You can distribute your modules with Python 3 support in different ways. A
normal source distribution will work, but can be slow in installing, as the
2to3 process will be run during the install. But you can also distribute
the module in binary format, such as a binary egg. That egg will contain the
already converted code, and hence no 2to3 conversion is needed during install.</p>
</div>
<div class="section" id="advanced-features">
<h3>Advanced features<a class="headerlink" href="#advanced-features" title="Permalink to this headline">¶</a></h3>
<p>If you don’t want to run the 2to3 conversion on the doctests in Python files,
you can turn that off by setting <code class="docutils literal notranslate"><span class="pre">setuptools.use_2to3_on_doctests</span> <span class="pre">=</span> <span class="pre">False</span></code>.</p>
</div>
</div>
<span id="document-development"></span><div class="section" id="development-on-setuptools">
<h2>Development on Setuptools<a class="headerlink" href="#development-on-setuptools" title="Permalink to this headline">¶</a></h2>
<p>Setuptools is maintained by the Python community under the Python Packaging
Authority (PyPA) and led by Jason R. Coombs.</p>
<p>This document describes the process by which Setuptools is developed.
This document assumes the reader has some passing familiarity with
<em>using</em> setuptools, the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module, and pip.  It
does not attempt to explain basic concepts like inter-project
dependencies, nor does it contain detailed lexical syntax for most
file formats.  Neither does it explain concepts like “namespace
packages” or “resources” in any detail, as all of these subjects are
covered at length in the setuptools developer’s guide and the
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> reference manual.</p>
<p>Instead, this is <strong>internal</strong> documentation for how those concepts and
features are <em>implemented</em> in concrete terms.  It is intended for people
who are working on the setuptools code base, who want to be able to
troubleshoot setuptools problems, want to write code that reads the file
formats involved, or want to otherwise tinker with setuptools-generated
files and directories.</p>
<p>Note, however, that these are all internal implementation details and
are therefore subject to change; stick to the published API if you don’t
want to be responsible for keeping your code from breaking when
setuptools changes.  You have been warned.</p>
<div class="toctree-wrapper compound">
<span id="document-developer-guide"></span><div class="section" id="developer-s-guide-for-setuptools">
<h3><a class="toc-backref" href="#id1">Developer’s Guide for Setuptools</a><a class="headerlink" href="#developer-s-guide-for-setuptools" title="Permalink to this headline">¶</a></h3>
<p>If you want to know more about contributing on Setuptools, this is the place.</p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><strong>Table of Contents</strong></p>
<ul class="simple">
<li><a class="reference internal" href="#developer-s-guide-for-setuptools" id="id1">Developer’s Guide for Setuptools</a><ul>
<li><a class="reference internal" href="#recommended-reading" id="id2">Recommended Reading</a></li>
<li><a class="reference internal" href="#project-management" id="id3">Project Management</a></li>
<li><a class="reference internal" href="#authoring-tickets" id="id4">Authoring Tickets</a></li>
<li><a class="reference internal" href="#making-a-pull-request" id="id5">Making a pull request</a></li>
<li><a class="reference internal" href="#auto-merge-requests" id="id6">Auto-Merge Requests</a></li>
<li><a class="reference internal" href="#testing" id="id7">Testing</a></li>
<li><a class="reference internal" href="#semantic-versioning" id="id8">Semantic Versioning</a></li>
<li><a class="reference internal" href="#building-documentation" id="id9">Building Documentation</a></li>
<li><a class="reference internal" href="#vendored-dependencies" id="id10">Vendored Dependencies</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="recommended-reading">
<h4><a class="toc-backref" href="#id2">Recommended Reading</a><a class="headerlink" href="#recommended-reading" title="Permalink to this headline">¶</a></h4>
<p>Please read <a class="reference external" href="https://blog.jaraco.com/how-to-write-perfect-pull-request/">How to write the perfect pull request</a> for some tips
on contributing to open source projects. Although the article is not
authoritative, it was authored by the maintainer of Setuptools, so reflects
his opinions and will improve the likelihood of acceptance and quality of
contribution.</p>
</div>
<div class="section" id="project-management">
<h4><a class="toc-backref" href="#id3">Project Management</a><a class="headerlink" href="#project-management" title="Permalink to this headline">¶</a></h4>
<p>Setuptools is maintained primarily in Github at <a class="reference external" href="https://github.com/pypa/setuptools">this home</a>. Setuptools is maintained under the
Python Packaging Authority (PyPA) with several core contributors. All bugs
for Setuptools are filed and the canonical source is maintained in Github.</p>
<p>User support and discussions are done through the issue tracker (for specific)
issues, through the distutils-sig mailing list, or on IRC (Freenode) at
#pypa.</p>
<p>Discussions about development happen on the pypa-dev mailing list or on
<a class="reference external" href="https://gitter.im/pypa/setuptools">Gitter</a>.</p>
</div>
<div class="section" id="authoring-tickets">
<h4><a class="toc-backref" href="#id4">Authoring Tickets</a><a class="headerlink" href="#authoring-tickets" title="Permalink to this headline">¶</a></h4>
<p>Before authoring any source code, it’s often prudent to file a ticket
describing the motivation behind making changes. First search to see if a
ticket already exists for your issue. If not, create one. Try to think from
the perspective of the reader. Explain what behavior you expected, what you
got instead, and what factors might have contributed to the unexpected
behavior. In Github, surround a block of code or traceback with the triple
backtick “```” so that it is formatted nicely.</p>
<p>Filing a ticket provides a forum for justification, discussion, and
clarification. The ticket provides a record of the purpose for the change and
any hard decisions that were made. It provides a single place for others to
reference when trying to understand why the software operates the way it does
or why certain changes were made.</p>
<p>Setuptools makes extensive use of hyperlinks to tickets in the changelog so
that system integrators and other users can get a quick summary, but then
jump to the in-depth discussion about any subject referenced.</p>
</div>
<div class="section" id="making-a-pull-request">
<h4><a class="toc-backref" href="#id5">Making a pull request</a><a class="headerlink" href="#making-a-pull-request" title="Permalink to this headline">¶</a></h4>
<p>When making a pull request, please include a short summary of the changes
and a reference to any issue tickets that the PR is intended to solve.
All PRs with code changes should include tests. All changes should include a
changelog entry.</p>
<p><code class="docutils literal notranslate"><span class="pre">setuptools</span></code> uses <a class="reference external" href="https://pypi.org/project/towncrier/">towncrier</a>
for changelog management, so when making a PR, please add a news fragment in the
<code class="docutils literal notranslate"><span class="pre">changelog.d/</span></code> folder. Changelog files are written in reStructuredText and
should be a 1 or 2 sentence description of the substantive changes in the PR.
They should be named <code class="docutils literal notranslate"><span class="pre">&lt;pr_number&gt;.&lt;category&gt;.rst</span></code>, where the categories are:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">change</span></code>: Any backwards compatible code change</li>
<li><code class="docutils literal notranslate"><span class="pre">breaking</span></code>: Any backwards-compatibility breaking change</li>
<li><code class="docutils literal notranslate"><span class="pre">doc</span></code>: A change to the documentation</li>
<li><code class="docutils literal notranslate"><span class="pre">misc</span></code>: Changes internal to the repo like CI, test and build changes</li>
<li><code class="docutils literal notranslate"><span class="pre">deprecation</span></code>: For deprecations of an existing feature or behavior</li>
</ul>
<p>A pull request may have more than one of these components, for example a code
change may introduce a new feature that deprecates an old feature, in which
case two fragments should be added. It is not necessary to make a separate
documentation fragment for documentation changes accompanying the relevant
code changes. See the following for an example news fragment:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ cat changelog.d/1288.change.rst
Add support <span class="k">for</span> maintainer in PKG-INFO
</pre></div>
</div>
</div>
<div class="section" id="auto-merge-requests">
<h4><a class="toc-backref" href="#id6">Auto-Merge Requests</a><a class="headerlink" href="#auto-merge-requests" title="Permalink to this headline">¶</a></h4>
<p>To support running all code through CI, even lightweight contributions,
the project employs Mergify to auto-merge pull requests tagged as
auto-merge.</p>
<p>Use <code class="docutils literal notranslate"><span class="pre">hub</span> <span class="pre">pull-request</span> <span class="pre">-l</span> <span class="pre">auto-merge</span></code> to create such a pull request
from the command line after pushing a new branch.</p>
</div>
<div class="section" id="testing">
<h4><a class="toc-backref" href="#id7">Testing</a><a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h4>
<p>The primary tests are run using tox.  Make sure you have tox installed,
and invoke it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ tox
</pre></div>
</div>
<p>Under continuous integration, additional tests may be run. See the
<code class="docutils literal notranslate"><span class="pre">.travis.yml</span></code> file for full details on the tests run under Travis-CI.</p>
</div>
<div class="section" id="semantic-versioning">
<h4><a class="toc-backref" href="#id8">Semantic Versioning</a><a class="headerlink" href="#semantic-versioning" title="Permalink to this headline">¶</a></h4>
<p>Setuptools follows <code class="docutils literal notranslate"><span class="pre">semver</span></code>.</p>
</div>
<div class="section" id="building-documentation">
<h4><a class="toc-backref" href="#id9">Building Documentation</a><a class="headerlink" href="#building-documentation" title="Permalink to this headline">¶</a></h4>
<p>Setuptools relies on the <a class="reference external" href="http://www.sphinx-doc.org/en/master/">Sphinx</a> system for building documentation.
The <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/">published documentation</a> is hosted on Read the Docs.</p>
<p>To build the docs locally, use tox:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ tox -e docs
</pre></div>
</div>
</div>
<div class="section" id="vendored-dependencies">
<h4><a class="toc-backref" href="#id10">Vendored Dependencies</a><a class="headerlink" href="#vendored-dependencies" title="Permalink to this headline">¶</a></h4>
<p>Setuptools has some dependencies, but due to <cite>bootstrapping issues
&lt;https://github.com/pypa/setuptools/issues/980&gt;</cite>, those dependencies
cannot be declared as they won’t be resolved soon enough to build
setuptools from source. Eventually, this limitation may be lifted as
PEP 517/518 reach ubiquitous adoption, but for now, Setuptools
cannot declare dependencies other than through
<code class="docutils literal notranslate"><span class="pre">setuptools/_vendor/vendored.txt</span></code> and
<code class="docutils literal notranslate"><span class="pre">pkg_reosurces/_vendor/vendored.txt</span></code> and refreshed by way of
<code class="docutils literal notranslate"><span class="pre">paver</span> <span class="pre">update_vendored</span></code> (pavement.py).</p>
</div>
</div>
<span id="document-formats"></span><div class="section" id="the-internal-structure-of-python-eggs">
<h3><a class="toc-backref" href="#id1">The Internal Structure of Python Eggs</a><a class="headerlink" href="#the-internal-structure-of-python-eggs" title="Permalink to this headline">¶</a></h3>
<p>STOP! This is not the first document you should read!</p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><strong>Table of Contents</strong></p>
<ul class="simple">
<li><a class="reference internal" href="#the-internal-structure-of-python-eggs" id="id1">The Internal Structure of Python Eggs</a><ul>
<li><a class="reference internal" href="#eggs-and-their-formats" id="id2">Eggs and their Formats</a><ul>
<li><a class="reference internal" href="#code-and-resources" id="id3">Code and Resources</a></li>
<li><a class="reference internal" href="#project-metadata" id="id4">Project Metadata</a></li>
<li><a class="reference internal" href="#filename-embedded-metadata" id="id5">Filename-Embedded Metadata</a></li>
<li><a class="reference internal" href="#egg-links" id="id6">Egg Links</a></li>
</ul>
</li>
<li><a class="reference internal" href="#standard-metadata" id="id7">Standard Metadata</a><ul>
<li><a class="reference internal" href="#txt-file-formats" id="id8"><code class="docutils literal notranslate"><span class="pre">.txt</span></code> File Formats</a></li>
<li><a class="reference internal" href="#dependency-metadata" id="id9">Dependency Metadata</a><ul>
<li><a class="reference internal" href="#requires-txt" id="id10"><code class="docutils literal notranslate"><span class="pre">requires.txt</span></code></a></li>
<li><a class="reference internal" href="#setup-requires-txt" id="id11"><code class="docutils literal notranslate"><span class="pre">setup_requires.txt</span></code></a></li>
<li><a class="reference internal" href="#dependency-links-txt" id="id12"><code class="docutils literal notranslate"><span class="pre">dependency_links.txt</span></code></a></li>
<li><a class="reference internal" href="#depends-txt-obsolete-do-not-create" id="id13"><code class="docutils literal notranslate"><span class="pre">depends.txt</span></code> – Obsolete, do not create!</a></li>
</ul>
</li>
<li><a class="reference internal" href="#namespace-packages-txt-namespace-package-metadata" id="id14"><code class="docutils literal notranslate"><span class="pre">namespace_packages.txt</span></code> – Namespace Package Metadata</a></li>
<li><a class="reference internal" href="#entry-points-txt-entry-point-plugin-metadata" id="id15"><code class="docutils literal notranslate"><span class="pre">entry_points.txt</span></code> – “Entry Point”/Plugin Metadata</a></li>
<li><a class="reference internal" href="#the-scripts-subdirectory" id="id16">The <code class="docutils literal notranslate"><span class="pre">scripts</span></code> Subdirectory</a></li>
<li><a class="reference internal" href="#zip-support-metadata" id="id17">Zip Support Metadata</a><ul>
<li><a class="reference internal" href="#native-libs-txt" id="id18"><code class="docutils literal notranslate"><span class="pre">native_libs.txt</span></code></a></li>
<li><a class="reference internal" href="#eager-resources-txt" id="id19"><code class="docutils literal notranslate"><span class="pre">eager_resources.txt</span></code></a></li>
<li><a class="reference internal" href="#zip-safe-and-not-zip-safe" id="id20"><code class="docutils literal notranslate"><span class="pre">zip-safe</span></code> and <code class="docutils literal notranslate"><span class="pre">not-zip-safe</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#top-level-txt-conflict-management-metadata" id="id21"><code class="docutils literal notranslate"><span class="pre">top_level.txt</span></code> – Conflict Management Metadata</a></li>
<li><a class="reference internal" href="#sources-txt-source-files-manifest" id="id22"><code class="docutils literal notranslate"><span class="pre">SOURCES.txt</span></code> – Source Files Manifest</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-technical-considerations" id="id23">Other Technical Considerations</a><ul>
<li><a class="reference internal" href="#zip-file-issues" id="id24">Zip File Issues</a><ul>
<li><a class="reference internal" href="#the-extraction-process" id="id25">The Extraction Process</a></li>
<li><a class="reference internal" href="#extension-import-wrappers" id="id26">Extension Import Wrappers</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installation-and-path-management-issues" id="id27">Installation and Path Management Issues</a><ul>
<li><a class="reference internal" href="#script-wrappers" id="id28">Script Wrappers</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="eggs-and-their-formats">
<h4><a class="toc-backref" href="#id2">Eggs and their Formats</a><a class="headerlink" href="#eggs-and-their-formats" title="Permalink to this headline">¶</a></h4>
<p>A “Python egg” is a logical structure embodying the release of a
specific version of a Python project, comprising its code, resources,
and metadata. There are multiple formats that can be used to physically
encode a Python egg, and others can be developed. However, a key
principle of Python eggs is that they should be discoverable and
importable. That is, it should be possible for a Python application to
easily and efficiently find out what eggs are present on a system, and
to ensure that the desired eggs’ contents are importable.</p>
<p>There are two basic formats currently implemented for Python eggs:</p>
<ol class="arabic simple">
<li><code class="docutils literal notranslate"><span class="pre">.egg</span></code> format: a directory or zipfile <em>containing</em> the project’s
code and resources, along with an <code class="docutils literal notranslate"><span class="pre">EGG-INFO</span></code> subdirectory that
contains the project’s metadata</li>
<li><code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> format: a file or directory placed <em>adjacent</em> to the
project’s code and resources, that directly contains the project’s
metadata.</li>
</ol>
<p>Both formats can include arbitrary Python code and resources, including
static data files, package and non-package directories, Python
modules, C extension modules, and so on.  But each format is optimized
for different purposes.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">.egg</span></code> format is well-suited to distribution and the easy
uninstallation or upgrades of code, since the project is essentially
self-contained within a single directory or file, unmingled with any
other projects’ code or resources.  It also makes it possible to have
multiple versions of a project simultaneously installed, such that
individual programs can select the versions they wish to use.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> format, on the other hand, was created to support
backward-compatibility, performance, and ease of installation for system
packaging tools that expect to install all projects’ code and resources
to a single directory (e.g. <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>).  Placing the metadata
in that same directory simplifies the installation process, since it
isn’t necessary to create <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files or otherwise modify
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> to include each installed egg.</p>
<p>Its disadvantage, however, is that it provides no support for clean
uninstallation or upgrades, and of course only a single version of a
project can be installed to a given directory. Thus, support from a
package management tool is required. (This is why setuptools’ “install”
command refers to this type of egg installation as “single-version,
externally managed”.)  Also, they lack sufficient data to allow them to
be copied from their installation source.  easy_install can “ship” an
application by copying <code class="docutils literal notranslate"><span class="pre">.egg</span></code> files or directories to a target
location, but it cannot do this for <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> installs, because
there is no way to tell what code and resources belong to a particular
egg – there may be several eggs “scrambled” together in a single
installation location, and the <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> format does not currently
include a way to list the files that were installed.  (This may change
in a future version.)</p>
<div class="section" id="code-and-resources">
<h5><a class="toc-backref" href="#id3">Code and Resources</a><a class="headerlink" href="#code-and-resources" title="Permalink to this headline">¶</a></h5>
<p>The layout of the code and resources is dictated by Python’s normal
import layout, relative to the egg’s “base location”.</p>
<p>For the <code class="docutils literal notranslate"><span class="pre">.egg</span></code> format, the base location is the <code class="docutils literal notranslate"><span class="pre">.egg</span></code> itself. That
is, adding the <code class="docutils literal notranslate"><span class="pre">.egg</span></code> filename or directory name to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>
makes its contents importable.</p>
<p>For the <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> format, however, the base location is the
directory that <em>contains</em> the <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code>, and thus it is the
directory that must be added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> to make the egg importable.
(Note that this means that the “normal” installation of a package to a
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> directory is sufficient to make it an “egg” if it has an
<code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> file or directory installed alongside of it.)</p>
</div>
<div class="section" id="project-metadata">
<h5><a class="toc-backref" href="#id4">Project Metadata</a><a class="headerlink" href="#project-metadata" title="Permalink to this headline">¶</a></h5>
<p>If eggs contained only code and resources, there would of course be
no difference between them and any other directory or zip file on
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.  Thus, metadata must also be included, using a metadata
file or directory.</p>
<p>For the <code class="docutils literal notranslate"><span class="pre">.egg</span></code> format, the metadata is placed in an <code class="docutils literal notranslate"><span class="pre">EGG-INFO</span></code>
subdirectory, directly within the <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file or directory.  For the
<code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> format, metadata is stored directly within the
<code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> directory itself.</p>
<p>The minimum project metadata that all eggs must have is a standard
Python <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> file, named <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> and placed within the
metadata directory appropriate to the format.  Because it’s possible for
this to be the only metadata file included, <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> format eggs
are not required to be a directory; they can just be a <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code>
file that directly contains the <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> metadata.  This eliminates
the need to create a directory just to store one file.  This option is
<em>not</em> available for <code class="docutils literal notranslate"><span class="pre">.egg</span></code> formats, since setuptools always includes
other metadata.  (In fact, setuptools itself never generates
<code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> files, either; the support for using files was added so
that the requirement could easily be satisfied by other tools, such
as distutils).</p>
<p>In addition to the <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> file, an egg’s metadata directory may
also include files and directories representing various forms of
optional standard metadata (see the section on <a class="reference internal" href="#standard-metadata">Standard Metadata</a>,
below) or user-defined metadata required by the project.  For example,
some projects may define a metadata format to describe their application
plugins, and metadata in this format would then be included by plugin
creators in their projects’ metadata directories.</p>
</div>
<div class="section" id="filename-embedded-metadata">
<h5><a class="toc-backref" href="#id5">Filename-Embedded Metadata</a><a class="headerlink" href="#filename-embedded-metadata" title="Permalink to this headline">¶</a></h5>
<p>To allow introspection of installed projects and runtime resolution of
inter-project dependencies, a certain amount of information is embedded
in egg filenames.  At a minimum, this includes the project name, and
ideally will also include the project version number.  Optionally, it
can also include the target Python version and required runtime
platform if platform-specific C code is included.  The syntax of an
egg filename is as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">name</span> <span class="p">[</span><span class="s2">&quot;-&quot;</span> <span class="n">version</span> <span class="p">[</span><span class="s2">&quot;-py&quot;</span> <span class="n">pyver</span> <span class="p">[</span><span class="s2">&quot;-&quot;</span> <span class="n">required_platform</span><span class="p">]]]</span> <span class="s2">&quot;.&quot;</span> <span class="n">ext</span>
</pre></div>
</div>
<p>The “name” and “version” should be escaped using the <code class="docutils literal notranslate"><span class="pre">to_filename()</span></code>
function provided by <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>, after first processing them with
<code class="docutils literal notranslate"><span class="pre">safe_name()</span></code> and <code class="docutils literal notranslate"><span class="pre">safe_version()</span></code> respectively.  These latter two
functions can also be used to later “unescape” these parts of the
filename.  (For a detailed description of these transformations, please
see the “Parsing Utilities” section of the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> manual.)</p>
<p>The “pyver” string is the Python major version, as found in the first
3 characters of <code class="docutils literal notranslate"><span class="pre">sys.version</span></code>.  “required_platform” is essentially
a distutils <code class="docutils literal notranslate"><span class="pre">get_platform()</span></code> string, but with enhancements to properly
distinguish Mac OS versions.  (See the <code class="docutils literal notranslate"><span class="pre">get_build_platform()</span></code>
documentation in the “Platform Utilities” section of the
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> manual for more details.)</p>
<p>Finally, the “ext” is either <code class="docutils literal notranslate"><span class="pre">.egg</span></code> or <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code>, as appropriate
for the egg’s format.</p>
<p>Normally, an egg’s filename should include at least the project name and
version, as this allows the runtime system to find desired project
versions without having to read the egg’s PKG-INFO to determine its
version number.</p>
<p>Setuptools, however, only includes the version number in the filename
when an <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file is built using the <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> command, or when
an <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> directory is being installed by the
<code class="docutils literal notranslate"><span class="pre">install_egg_info</span></code> command. When generating metadata for use with the
original source tree, it only includes the project name, so that the
directory will not have to be renamed each time the project’s version
changes.</p>
<p>This is especially important when version numbers change frequently, and
the source metadata directory is kept under version control with the
rest of the project.  (As would be the case when the project’s source
includes project-defined metadata that is not generated from by
setuptools from data in the setup script.)</p>
</div>
<div class="section" id="egg-links">
<h5><a class="toc-backref" href="#id6">Egg Links</a><a class="headerlink" href="#egg-links" title="Permalink to this headline">¶</a></h5>
<p>In addition to the <code class="docutils literal notranslate"><span class="pre">.egg</span></code> and <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> formats, there is a third
egg-related extension that you may encounter on occasion: <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code>
files.</p>
<p>These files are not eggs, strictly speaking. They simply provide a way
to reference an egg that is not physically installed in the desired
location. They exist primarily as a cross-platform alternative to
symbolic links, to support “installing” code that is being developed in
a different location than the desired installation location. For
example, if a user is developing an application plugin in their home
directory, but the plugin needs to be “installed” in an application
plugin directory, running “setup.py develop -md /path/to/app/plugins”
will install an <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> file in <code class="docutils literal notranslate"><span class="pre">/path/to/app/plugins</span></code>, that
tells the egg runtime system where to find the actual egg (the user’s
project source directory and its <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> subdirectory).</p>
<p><code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> files are named following the format for <code class="docutils literal notranslate"><span class="pre">.egg</span></code> and
<code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> names, but only the project name is included; no version,
Python version, or platform information is included.  When the runtime
searches for available eggs, <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> files are opened and the
actual egg file/directory name is read from them.</p>
<p>Each <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> file should contain a single file or directory name,
with no newlines.  This filename should be the base location of one or
more eggs.  That is, the name must either end in <code class="docutils literal notranslate"><span class="pre">.egg</span></code>, or else it
should be the parent directory of one or more <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> format eggs.</p>
<p>As of setuptools 0.6c6, the path may be specified as a platform-independent
(i.e. <code class="docutils literal notranslate"><span class="pre">/</span></code>-separated) relative path from the directory containing the
<code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> file, and a second line may appear in the file, specifying a
platform-independent relative path from the egg’s base directory to its
setup script directory.  This allows installation tools such as EasyInstall
to find the project’s setup directory and build eggs or perform other setup
commands on it.</p>
</div>
</div>
<div class="section" id="standard-metadata">
<h4><a class="toc-backref" href="#id7">Standard Metadata</a><a class="headerlink" href="#standard-metadata" title="Permalink to this headline">¶</a></h4>
<p>In addition to the minimum required <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> metadata, projects can
include a variety of standard metadata files or directories, as
described below.  Except as otherwise noted, these files and directories
are automatically generated by setuptools, based on information supplied
in the setup script or through analysis of the project’s code and
resources.</p>
<p>Most of these files and directories are generated via “egg-info
writers” during execution of the setuptools <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command, and
are listed in the <code class="docutils literal notranslate"><span class="pre">egg_info.writers</span></code> entry point group defined by
setuptools’ own <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> file.</p>
<p>Project authors can register their own metadata writers as entry points
in this group (as described in the setuptools manual under “Adding new
EGG-INFO Files”) to cause setuptools to generate project-specific
metadata files or directories during execution of the <code class="docutils literal notranslate"><span class="pre">egg_info</span></code>
command.  It is up to project authors to document these new metadata
formats, if they create any.</p>
<div class="section" id="txt-file-formats">
<h5><a class="toc-backref" href="#id8"><code class="docutils literal notranslate"><span class="pre">.txt</span></code> File Formats</a><a class="headerlink" href="#txt-file-formats" title="Permalink to this headline">¶</a></h5>
<p>Files described in this section that have <code class="docutils literal notranslate"><span class="pre">.txt</span></code> extensions have a
simple lexical format consisting of a sequence of text lines, each line
terminated by a linefeed character (regardless of platform).  Leading
and trailing whitespace on each line is ignored, as are blank lines and
lines whose first nonblank character is a <code class="docutils literal notranslate"><span class="pre">#</span></code> (comment symbol).  (This
is the parsing format defined by the <code class="docutils literal notranslate"><span class="pre">yield_lines()</span></code> function of
the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module.)</p>
<p>All <code class="docutils literal notranslate"><span class="pre">.txt</span></code> files defined by this section follow this format, but some
are also “sectioned” files, meaning that their contents are divided into
sections, using square-bracketed section headers akin to Windows
<code class="docutils literal notranslate"><span class="pre">.ini</span></code> format.  Note that this does <em>not</em> imply that the lines within
the sections follow an <code class="docutils literal notranslate"><span class="pre">.ini</span></code> format, however.  Please see an
individual metadata file’s documentation for a description of what the
lines and section names mean in that particular file.</p>
<p>Sectioned files can be parsed using the <code class="docutils literal notranslate"><span class="pre">split_sections()</span></code> function;
see the “Parsing Utilities” section of the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> manual for
for details.</p>
</div>
<div class="section" id="dependency-metadata">
<h5><a class="toc-backref" href="#id9">Dependency Metadata</a><a class="headerlink" href="#dependency-metadata" title="Permalink to this headline">¶</a></h5>
<div class="section" id="requires-txt">
<h6><a class="toc-backref" href="#id10"><code class="docutils literal notranslate"><span class="pre">requires.txt</span></code></a><a class="headerlink" href="#requires-txt" title="Permalink to this headline">¶</a></h6>
<p>This is a “sectioned” text file.  Each section is a sequence of
“requirements”, as parsed by the <code class="docutils literal notranslate"><span class="pre">parse_requirements()</span></code> function;
please see the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> manual for the complete requirement
parsing syntax.</p>
<p>The first, unnamed section (i.e., before the first section header) in
this file is the project’s core requirements, which must be installed
for the project to function.  (Specified using the <code class="docutils literal notranslate"><span class="pre">install_requires</span></code>
keyword to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>).</p>
<p>The remaining (named) sections describe the project’s “extra”
requirements, as specified using the <code class="docutils literal notranslate"><span class="pre">extras_require</span></code> keyword to
<code class="docutils literal notranslate"><span class="pre">setup()</span></code>.  The section name is the name of the optional feature, and
the section body lists that feature’s dependencies.</p>
<p>Note that it is not normally necessary to inspect this file directly;
<code class="docutils literal notranslate"><span class="pre">pkg_resources.Distribution</span></code> objects have a <code class="docutils literal notranslate"><span class="pre">requires()</span></code> method
that can be used to obtain <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> objects describing the
project’s core and optional dependencies.</p>
</div>
<div class="section" id="setup-requires-txt">
<h6><a class="toc-backref" href="#id11"><code class="docutils literal notranslate"><span class="pre">setup_requires.txt</span></code></a><a class="headerlink" href="#setup-requires-txt" title="Permalink to this headline">¶</a></h6>
<p>Much like <code class="docutils literal notranslate"><span class="pre">requires.txt</span></code> except represents the requirements
specified by the <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> parameter to the Distribution.</p>
</div>
<div class="section" id="dependency-links-txt">
<h6><a class="toc-backref" href="#id12"><code class="docutils literal notranslate"><span class="pre">dependency_links.txt</span></code></a><a class="headerlink" href="#dependency-links-txt" title="Permalink to this headline">¶</a></h6>
<p>A list of dependency URLs, one per line, as specified using the
<code class="docutils literal notranslate"><span class="pre">dependency_links</span></code> keyword to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>.  These may be direct
download URLs, or the URLs of web pages containing direct download
links. Please see the setuptools manual for more information on
specifying this option.</p>
</div>
<div class="section" id="depends-txt-obsolete-do-not-create">
<h6><a class="toc-backref" href="#id13"><code class="docutils literal notranslate"><span class="pre">depends.txt</span></code> – Obsolete, do not create!</a><a class="headerlink" href="#depends-txt-obsolete-do-not-create" title="Permalink to this headline">¶</a></h6>
<p>This file follows an identical format to <code class="docutils literal notranslate"><span class="pre">requires.txt</span></code>, but is
obsolete and should not be used.  The earliest versions of setuptools
required users to manually create and maintain this file, so the runtime
still supports reading it, if it exists.  The new filename was created
so that it could be automatically generated from <code class="docutils literal notranslate"><span class="pre">setup()</span></code> information
without overwriting an existing hand-created <code class="docutils literal notranslate"><span class="pre">depends.txt</span></code>, if one
was already present in the project’s source <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> directory.</p>
</div>
</div>
<div class="section" id="namespace-packages-txt-namespace-package-metadata">
<h5><a class="toc-backref" href="#id14"><code class="docutils literal notranslate"><span class="pre">namespace_packages.txt</span></code> – Namespace Package Metadata</a><a class="headerlink" href="#namespace-packages-txt-namespace-package-metadata" title="Permalink to this headline">¶</a></h5>
<p>A list of namespace package names, one per line, as supplied to the
<code class="docutils literal notranslate"><span class="pre">namespace_packages</span></code> keyword to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>.  Please see the manuals
for setuptools and <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> for more information about
namespace packages.</p>
</div>
<div class="section" id="entry-points-txt-entry-point-plugin-metadata">
<h5><a class="toc-backref" href="#id15"><code class="docutils literal notranslate"><span class="pre">entry_points.txt</span></code> – “Entry Point”/Plugin Metadata</a><a class="headerlink" href="#entry-points-txt-entry-point-plugin-metadata" title="Permalink to this headline">¶</a></h5>
<p>This is a “sectioned” text file, whose contents encode the
<code class="docutils literal notranslate"><span class="pre">entry_points</span></code> keyword supplied to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>.  All sections are
named, as the section names specify the entry point groups in which the
corresponding section’s entry points are registered.</p>
<p>Each section is a sequence of “entry point” lines, each parseable using
the <code class="docutils literal notranslate"><span class="pre">EntryPoint.parse</span></code> classmethod; please see the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>
manual for the complete entry point parsing syntax.</p>
<p>Note that it is not necessary to parse this file directly; the
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module provides a variety of APIs to locate and load
entry points automatically.  Please see the setuptools and
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> manuals for details on the nature and uses of entry
points.</p>
</div>
<div class="section" id="the-scripts-subdirectory">
<h5><a class="toc-backref" href="#id16">The <code class="docutils literal notranslate"><span class="pre">scripts</span></code> Subdirectory</a><a class="headerlink" href="#the-scripts-subdirectory" title="Permalink to this headline">¶</a></h5>
<p>This directory is currently only created for <code class="docutils literal notranslate"><span class="pre">.egg</span></code> files built by
the setuptools <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> command.  It will contain copies of all
of the project’s “traditional” scripts (i.e., those specified using the
<code class="docutils literal notranslate"><span class="pre">scripts</span></code> keyword to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>).  This is so that they can be
reconstituted when an <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file is installed.</p>
<p>The scripts are placed here using the distutils’ standard
<code class="docutils literal notranslate"><span class="pre">install_scripts</span></code> command, so any <code class="docutils literal notranslate"><span class="pre">#!</span></code> lines reflect the Python
installation where the egg was built.  But instead of copying the
scripts to the local script installation directory, EasyInstall writes
short wrapper scripts that invoke the original scripts from inside the
egg, after ensuring that sys.path includes the egg and any eggs it
depends on.  For more about <a class="reference internal" href="#script-wrappers">script wrappers</a>, see the section below on
<a class="reference internal" href="#installation-and-path-management-issues">Installation and Path Management Issues</a>.</p>
</div>
<div class="section" id="zip-support-metadata">
<h5><a class="toc-backref" href="#id17">Zip Support Metadata</a><a class="headerlink" href="#zip-support-metadata" title="Permalink to this headline">¶</a></h5>
<div class="section" id="native-libs-txt">
<h6><a class="toc-backref" href="#id18"><code class="docutils literal notranslate"><span class="pre">native_libs.txt</span></code></a><a class="headerlink" href="#native-libs-txt" title="Permalink to this headline">¶</a></h6>
<p>A list of C extensions and other dynamic link libraries contained in
the egg, one per line.  Paths are <code class="docutils literal notranslate"><span class="pre">/</span></code>-separated and relative to the
egg’s base location.</p>
<p>This file is generated as part of <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> processing, and as such
only appears in <code class="docutils literal notranslate"><span class="pre">.egg</span></code> files (and <code class="docutils literal notranslate"><span class="pre">.egg</span></code> directories created by
unpacking them).  It is used to ensure that all libraries are extracted
from a zipped egg at the same time, in case there is any direct linkage
between them.  Please see the <a class="reference internal" href="#zip-file-issues">Zip File Issues</a> section below for more
information on library and resource extraction from <code class="docutils literal notranslate"><span class="pre">.egg</span></code> files.</p>
</div>
<div class="section" id="eager-resources-txt">
<h6><a class="toc-backref" href="#id19"><code class="docutils literal notranslate"><span class="pre">eager_resources.txt</span></code></a><a class="headerlink" href="#eager-resources-txt" title="Permalink to this headline">¶</a></h6>
<p>A list of resource files and/or directories, one per line, as specified
via the <code class="docutils literal notranslate"><span class="pre">eager_resources</span></code> keyword to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>.  Paths are
<code class="docutils literal notranslate"><span class="pre">/</span></code>-separated and relative to the egg’s base location.</p>
<p>Resource files or directories listed here will be extracted
simultaneously, if any of the named resources are extracted, or if any
native libraries listed in <code class="docutils literal notranslate"><span class="pre">native_libs.txt</span></code> are extracted.  Please
see the setuptools manual for details on what this feature is used for
and how it works, as well as the <a class="reference internal" href="#zip-file-issues">Zip File Issues</a> section below.</p>
</div>
<div class="section" id="zip-safe-and-not-zip-safe">
<h6><a class="toc-backref" href="#id20"><code class="docutils literal notranslate"><span class="pre">zip-safe</span></code> and <code class="docutils literal notranslate"><span class="pre">not-zip-safe</span></code></a><a class="headerlink" href="#zip-safe-and-not-zip-safe" title="Permalink to this headline">¶</a></h6>
<p>These are zero-length files, and either one or the other should exist.
If <code class="docutils literal notranslate"><span class="pre">zip-safe</span></code> exists, it means that the project will work properly
when installed as an <code class="docutils literal notranslate"><span class="pre">.egg</span></code> zipfile, and conversely the existence of
<code class="docutils literal notranslate"><span class="pre">not-zip-safe</span></code> means the project should not be installed as an
<code class="docutils literal notranslate"><span class="pre">.egg</span></code> file.  The <code class="docutils literal notranslate"><span class="pre">zip_safe</span></code> option to setuptools’ <code class="docutils literal notranslate"><span class="pre">setup()</span></code>
determines which file will be written. If the option isn’t provided,
setuptools attempts to make its own assessment of whether the package
can work, based on code and content analysis.</p>
<p>If neither file is present at installation time, EasyInstall defaults
to assuming that the project should be unzipped.  (Command-line options
to EasyInstall, however, take precedence even over an existing
<code class="docutils literal notranslate"><span class="pre">zip-safe</span></code> or <code class="docutils literal notranslate"><span class="pre">not-zip-safe</span></code> file.)</p>
<p>Note that these flag files appear only in <code class="docutils literal notranslate"><span class="pre">.egg</span></code> files generated by
<code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code>, and in <code class="docutils literal notranslate"><span class="pre">.egg</span></code> directories created by unpacking such an
<code class="docutils literal notranslate"><span class="pre">.egg</span></code> file.</p>
</div>
</div>
<div class="section" id="top-level-txt-conflict-management-metadata">
<h5><a class="toc-backref" href="#id21"><code class="docutils literal notranslate"><span class="pre">top_level.txt</span></code> – Conflict Management Metadata</a><a class="headerlink" href="#top-level-txt-conflict-management-metadata" title="Permalink to this headline">¶</a></h5>
<p>This file is a list of the top-level module or package names provided
by the project, one Python identifier per line.</p>
<p>Subpackages are not included; a project containing both a <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code>
and a <code class="docutils literal notranslate"><span class="pre">foo.baz</span></code> would include only one line, <code class="docutils literal notranslate"><span class="pre">foo</span></code>, in its
<code class="docutils literal notranslate"><span class="pre">top_level.txt</span></code>.</p>
<p>This data is used by <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> at runtime to issue a warning if
an egg is added to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> when its contained packages may have
already been imported.</p>
<p>(It was also once used to detect conflicts with non-egg packages at
installation time, but in more recent versions, setuptools installs eggs
in such a way that they always override non-egg packages, thus
preventing a problem from arising.)</p>
</div>
<div class="section" id="sources-txt-source-files-manifest">
<h5><a class="toc-backref" href="#id22"><code class="docutils literal notranslate"><span class="pre">SOURCES.txt</span></code> – Source Files Manifest</a><a class="headerlink" href="#sources-txt-source-files-manifest" title="Permalink to this headline">¶</a></h5>
<p>This file is roughly equivalent to the distutils’ <code class="docutils literal notranslate"><span class="pre">MANIFEST</span></code> file.
The differences are as follows:</p>
<ul class="simple">
<li>The filenames always use <code class="docutils literal notranslate"><span class="pre">/</span></code> as a path separator, which must be
converted back to a platform-specific path whenever they are read.</li>
<li>The file is automatically generated by setuptools whenever the
<code class="docutils literal notranslate"><span class="pre">egg_info</span></code> or <code class="docutils literal notranslate"><span class="pre">sdist</span></code> commands are run, and it is <em>not</em>
user-editable.</li>
</ul>
<p>Although this metadata is included with distributed eggs, it is not
actually used at runtime for any purpose.  Its function is to ensure
that setuptools-built <em>source</em> distributions can correctly discover
what files are part of the project’s source, even if the list had been
generated using revision control metadata on the original author’s
system.</p>
<p>In other words, <code class="docutils literal notranslate"><span class="pre">SOURCES.txt</span></code> has little or no runtime value for being
included in distributed eggs, and it is possible that future versions of
the <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> and <code class="docutils literal notranslate"><span class="pre">install_egg_info</span></code> commands will strip it before
installation or distribution.  Therefore, do not rely on its being
available outside of an original source directory or source
distribution.</p>
</div>
</div>
<div class="section" id="other-technical-considerations">
<h4><a class="toc-backref" href="#id23">Other Technical Considerations</a><a class="headerlink" href="#other-technical-considerations" title="Permalink to this headline">¶</a></h4>
<div class="section" id="zip-file-issues">
<h5><a class="toc-backref" href="#id24">Zip File Issues</a><a class="headerlink" href="#zip-file-issues" title="Permalink to this headline">¶</a></h5>
<p>Although zip files resemble directories, they are not fully
substitutable for them.  Most platforms do not support loading dynamic
link libraries contained in zipfiles, so it is not possible to directly
import C extensions from <code class="docutils literal notranslate"><span class="pre">.egg</span></code> zipfiles.  Similarly, there are many
existing libraries – whether in Python or C – that require actual
operating system filenames, and do not work with arbitrary “file-like”
objects or in-memory strings, and thus cannot operate directly on the
contents of zip files.</p>
<p>To address these issues, the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module provides a
“resource API” to support obtaining either the contents of a resource,
or a true operating system filename for the resource.  If the egg
containing the resource is a directory, the resource’s real filename
is simply returned.  However, if the egg is a zipfile, then the
resource is first extracted to a cache directory, and the filename
within the cache is returned.</p>
<p>The cache directory is determined by the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> API; please
see the <code class="docutils literal notranslate"><span class="pre">set_cache_path()</span></code> and <code class="docutils literal notranslate"><span class="pre">get_default_cache()</span></code> documentation
for details.</p>
<div class="section" id="the-extraction-process">
<h6><a class="toc-backref" href="#id25">The Extraction Process</a><a class="headerlink" href="#the-extraction-process" title="Permalink to this headline">¶</a></h6>
<p>Resources are extracted to a cache subdirectory whose name is based
on the enclosing <code class="docutils literal notranslate"><span class="pre">.egg</span></code> filename and the path to the resource.  If
there is already a file of the correct name, size, and timestamp, its
filename is returned to the requester.  Otherwise, the desired file is
extracted first to a temporary name generated using
<code class="docutils literal notranslate"><span class="pre">mkstemp(&quot;.$extract&quot;,target_dir)</span></code>, and then its timestamp is set to
match the one in the zip file, before renaming it to its final name.
(Some collision detection and resolution code is used to handle the
fact that Windows doesn’t overwrite files when renaming.)</p>
<p>If a resource directory is requested, all of its contents are
recursively extracted in this fashion, to ensure that the directory
name can be used as if it were valid all along.</p>
<p>If the resource requested for extraction is listed in the
<code class="docutils literal notranslate"><span class="pre">native_libs.txt</span></code> or <code class="docutils literal notranslate"><span class="pre">eager_resources.txt</span></code> metadata files, then
<em>all</em> resources listed in <em>either</em> file will be extracted before the
requested resource’s filename is returned, thus ensuring that all
C extensions and data used by them will be simultaneously available.</p>
</div>
<div class="section" id="extension-import-wrappers">
<h6><a class="toc-backref" href="#id26">Extension Import Wrappers</a><a class="headerlink" href="#extension-import-wrappers" title="Permalink to this headline">¶</a></h6>
<p>Since Python’s built-in zip import feature does not support loading
C extension modules from zipfiles, the setuptools <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> command
generates special import wrappers to make it work.</p>
<p>The wrappers are <code class="docutils literal notranslate"><span class="pre">.py</span></code> files (along with corresponding <code class="docutils literal notranslate"><span class="pre">.pyc</span></code>
and/or <code class="docutils literal notranslate"><span class="pre">.pyo</span></code> files) that have the same module name as the
corresponding C extension.  These wrappers are located in the same
package directory (or top-level directory) within the zipfile, so that
say, <code class="docutils literal notranslate"><span class="pre">foomodule.so</span></code> will get a corresponding <code class="docutils literal notranslate"><span class="pre">foo.py</span></code>, while
<code class="docutils literal notranslate"><span class="pre">bar/baz.pyd</span></code> will get a corresponding <code class="docutils literal notranslate"><span class="pre">bar/baz.py</span></code>.</p>
<p>These wrapper files contain a short stanza of Python code that asks
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> for the filename of the corresponding C extension,
then reloads the module using the obtained filename.  This will cause
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> to first ensure that all of the egg’s C extensions
(and any accompanying “eager resources”) are extracted to the cache
before attempting to link to the C library.</p>
<p>Note, by the way, that <code class="docutils literal notranslate"><span class="pre">.egg</span></code> directories will also contain these
wrapper files.  However, Python’s default import priority is such that
C extensions take precedence over same-named Python modules, so the
import wrappers are ignored unless the egg is a zipfile.</p>
</div>
</div>
<div class="section" id="installation-and-path-management-issues">
<h5><a class="toc-backref" href="#id27">Installation and Path Management Issues</a><a class="headerlink" href="#installation-and-path-management-issues" title="Permalink to this headline">¶</a></h5>
<p>Python’s initial setup of <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> is very dependent on the Python
version and installation platform, as well as how Python was started
(i.e., script vs. <code class="docutils literal notranslate"><span class="pre">-c</span></code> vs. <code class="docutils literal notranslate"><span class="pre">-m</span></code> vs. interactive interpreter).
In fact, Python also provides only two relatively robust ways to affect
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> outside of direct manipulation in code: the <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code>
environment variable, and <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files.</p>
<p>However, with no cross-platform way to safely and persistently change
environment variables, this leaves <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files as EasyInstall’s only
real option for persistent configuration of <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.</p>
<p>But <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files are rather strictly limited in what they are allowed
to do normally.  They add directories only to the <em>end</em> of <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>,
after any locally-installed <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory, and they are
only processed <em>in</em> the <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory to start with.</p>
<p>This is a double whammy for users who lack write access to that
directory, because they can’t create a <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file that Python will
read, and even if a sympathetic system administrator adds one for them
that calls <code class="docutils literal notranslate"><span class="pre">site.addsitedir()</span></code> to allow some other directory to
contain <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files, they won’t be able to install newer versions of
anything that’s installed in the systemwide <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>, because
their paths will still be added <em>after</em> <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>.</p>
<p>So EasyInstall applies two workarounds to solve these problems.</p>
<p>The first is that EasyInstall leverages <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files’ “import” feature
to manipulate <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> and ensure that anything EasyInstall adds
to a <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file will always appear before both the standard library
and the local <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directories.  Thus, it is always
possible for a user who can write a Python-read <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file to ensure
that their packages come first in their own environment.</p>
<p>Second, when installing to a <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> directory (as opposed to
a “site” directory like <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>) EasyInstall will also install
a special version of the <code class="docutils literal notranslate"><span class="pre">site</span></code> module.  Because it’s in a
<code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> directory, this module will get control before the
standard library version of <code class="docutils literal notranslate"><span class="pre">site</span></code> does.  It will record the state of
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> before invoking the “real” <code class="docutils literal notranslate"><span class="pre">site</span></code> module, and then
afterwards it processes any <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files found in <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code>
directories, including all the fixups needed to ensure that eggs always
appear before the standard library in sys.path, but are in a relative
order to one another that is defined by their <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> and
<code class="docutils literal notranslate"><span class="pre">.pth</span></code>-prescribed sequence.</p>
<p>The net result of these changes is that <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> order will be
as follows at runtime:</p>
<ol class="arabic simple">
<li>The <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> directory, or an empty string if no script
is being executed.</li>
<li>All eggs installed by EasyInstall in any <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file in each
<code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> directory, in order first by <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> order,
then normal <code class="docutils literal notranslate"><span class="pre">.pth</span></code> processing order (which is to say alphabetical
by <code class="docutils literal notranslate"><span class="pre">.pth</span></code> filename, then by the order of listing within each
<code class="docutils literal notranslate"><span class="pre">.pth</span></code> file).</li>
<li>All eggs installed by EasyInstall in any <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file in each “site”
directory (such as <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>), following the same ordering
rules as for the ones on <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code>.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> directories themselves, in their original order</li>
<li>Any paths from <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files found on <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> that were <em>not</em>
eggs installed by EasyInstall, again following the same relative
ordering rules.</li>
<li>The standard library and “site” directories, along with the contents
of any <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files found in the “site” directories.</li>
</ol>
<p>Notice that sections 1, 4, and 6 comprise the “normal” Python setup for
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.  Sections 2 and 3 are inserted to support eggs, and
section 5 emulates what the “normal” semantics of <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files on
<code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> would be if Python natively supported them.</p>
<p>For further discussion of the tradeoffs that went into this design, as
well as notes on the actual magic inserted into <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files to make
them do these things, please see also the following messages to the
distutils-SIG mailing list:</p>
<ul class="simple">
<li><a class="reference external" href="http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html">http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html</a></li>
<li><a class="reference external" href="http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html">http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html</a></li>
</ul>
<div class="section" id="script-wrappers">
<h6><a class="toc-backref" href="#id28">Script Wrappers</a><a class="headerlink" href="#script-wrappers" title="Permalink to this headline">¶</a></h6>
<p>EasyInstall never directly installs a project’s original scripts to
a script installation directory.  Instead, it writes short wrapper
scripts that first ensure that the project’s dependencies are active
on sys.path, before invoking the original script.  These wrappers
have a #! line that points to the version of Python that was used to
install them, and their second line is always a comment that indicates
the type of script wrapper, the project version required for the script
to run, and information identifying the script to be invoked.</p>
<p>The format of this marker line is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;# EASY-INSTALL-&quot;</span> <span class="n">script_type</span> <span class="s2">&quot;: &quot;</span> <span class="n">tuple_of_strings</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">script_type</span></code> is one of <code class="docutils literal notranslate"><span class="pre">SCRIPT</span></code>, <code class="docutils literal notranslate"><span class="pre">DEV-SCRIPT</span></code>, or
<code class="docutils literal notranslate"><span class="pre">ENTRY-SCRIPT</span></code>.  The <code class="docutils literal notranslate"><span class="pre">tuple_of_strings</span></code> is a comma-separated
sequence of Python string constants.  For <code class="docutils literal notranslate"><span class="pre">SCRIPT</span></code> and <code class="docutils literal notranslate"><span class="pre">DEV-SCRIPT</span></code>
wrappers, there are two strings: the project version requirement, and
the script name (as a filename within the <code class="docutils literal notranslate"><span class="pre">scripts</span></code> metadata
directory).  For <code class="docutils literal notranslate"><span class="pre">ENTRY-SCRIPT</span></code> wrappers, there are three:
the project version requirement, the entry point group name, and the
entry point name.  (See the “Automatic Script Creation” section in the
setuptools manual for more information about entry point scripts.)</p>
<p>In each case, the project version requirement string will be a string
parseable with the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> modules’ <code class="docutils literal notranslate"><span class="pre">Requirement.parse()</span></code>
classmethod.  The only difference between a <code class="docutils literal notranslate"><span class="pre">SCRIPT</span></code> wrapper and a
<code class="docutils literal notranslate"><span class="pre">DEV-SCRIPT</span></code> is that a <code class="docutils literal notranslate"><span class="pre">DEV-SCRIPT</span></code> actually executes the original
source script in the project’s source tree, and is created when the
“setup.py develop” command is run.  A <code class="docutils literal notranslate"><span class="pre">SCRIPT</span></code> wrapper, on the other
hand, uses the “installed” script written to the <code class="docutils literal notranslate"><span class="pre">EGG-INFO/scripts</span></code>
subdirectory of the corresponding <code class="docutils literal notranslate"><span class="pre">.egg</span></code> zipfile or directory.
(<code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> eggs do not have script wrappers associated with them,
except in the “setup.py develop” case.)</p>
<p>The purpose of including the marker line in generated script wrappers is
to facilitate introspection of installed scripts, and their relationship
to installed eggs.  For example, an uninstallation tool could use this
data to identify what scripts can safely be removed, and/or identify
what scripts would stop working if a particular egg is uninstalled.</p>
</div>
</div>
</div>
</div>
<span id="document-releases"></span><div class="section" id="release-process">
<h3>Release Process<a class="headerlink" href="#release-process" title="Permalink to this headline">¶</a></h3>
<p>In order to allow for rapid, predictable releases, Setuptools uses a
mechanical technique for releases, enacted on tagged commits by
continuous integration.</p>
<p>To finalize a release, run <code class="docutils literal notranslate"><span class="pre">tox</span> <span class="pre">-e</span> <span class="pre">finalize</span></code>, review, then push
the changes.</p>
<p>If tests pass, the release will be uploaded to PyPI.</p>
<div class="section" id="release-frequency">
<h4>Release Frequency<a class="headerlink" href="#release-frequency" title="Permalink to this headline">¶</a></h4>
<p>Some have asked why Setuptools is released so frequently. Because Setuptools
uses a mechanical release process, it’s very easy to make releases whenever the
code is stable (tests are passing). As a result, the philosophy is to release
early and often.</p>
<p>While some find the frequent releases somewhat surprising, they only empower
the user. Although releases are made frequently, users can choose the frequency
at which they use those releases. If instead Setuptools contributions were only
released in batches, the user would be constrained to only use Setuptools when
those official releases were made. With frequent releases, the user can govern
exactly how often he wishes to update.</p>
<p>Frequent releases also then obviate the need for dev or beta releases in most
cases. Because releases are made early and often, bugs are discovered and
corrected quickly, in many cases before other users have yet to encounter them.</p>
</div>
<div class="section" id="release-managers">
<h4>Release Managers<a class="headerlink" href="#release-managers" title="Permalink to this headline">¶</a></h4>
<p>Additionally, anyone with push access to the master branch has access to cut
releases.</p>
</div>
</div>
</div>
</div>
<span id="document-roadmap"></span><div class="section" id="roadmap">
<h2>Roadmap<a class="headerlink" href="#roadmap" title="Permalink to this headline">¶</a></h2>
<p>Setuptools maintains a series of <a class="reference external" href="https://github.com/pypa/setuptools/milestones">milestones</a> to track
a roadmap of large-scale goals.</p>
</div>
<span id="document-easy_install"></span><div class="section" id="easy-install">
<h2><a class="toc-backref" href="#id6">Easy Install</a><a class="headerlink" href="#easy-install" title="Permalink to this headline">¶</a></h2>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Easy Install is deprecated. Do not use it. Instead use pip. If
you think you need Easy Install, please reach out to the PyPA
team (a ticket to pip or setuptools is fine), describing your
use-case.</p>
</div>
<p>Easy Install is a python module (<code class="docutils literal notranslate"><span class="pre">easy_install</span></code>) bundled with <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>
that lets you automatically download, build, install, and manage Python
packages.</p>
<p>Please share your experiences with us! If you encounter difficulty installing
a package, please contact us via the <a class="reference external" href="http://mail.python.org/pipermail/distutils-sig/">distutils mailing list</a>.  (Note: please DO NOT send
private email directly to the author of setuptools; it will be discarded.  The
mailing list is a searchable archive of previously-asked and answered
questions; you should begin your research there before reporting something as a
bug – and then do so via list discussion first.)</p>
<p>(Also, if you’d like to learn about how you can use <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> to make your
own packages work better with EasyInstall, or provide EasyInstall-like features
without requiring your users to use EasyInstall directly, you’ll probably want
to check out the full documentation as well.)</p>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><strong>Table of Contents</strong></p>
<ul class="simple">
<li><a class="reference internal" href="#easy-install" id="id6">Easy Install</a><ul>
<li><a class="reference internal" href="#using-easy-install" id="id7">Using “Easy Install”</a><ul>
<li><a class="reference internal" href="#installing-easy-install" id="id8">Installing “Easy Install”</a><ul>
<li><a class="reference internal" href="#troubleshooting" id="id9">Troubleshooting</a></li>
<li><a class="reference internal" href="#windows-notes" id="id10">Windows Notes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#downloading-and-installing-a-package" id="id11">Downloading and Installing a Package</a></li>
<li><a class="reference internal" href="#upgrading-a-package" id="id12">Upgrading a Package</a></li>
<li><a class="reference internal" href="#changing-the-active-version" id="id13">Changing the Active Version</a></li>
<li><a class="reference internal" href="#uninstalling-packages" id="id14">Uninstalling Packages</a></li>
<li><a class="reference internal" href="#managing-scripts" id="id15">Managing Scripts</a></li>
<li><a class="reference internal" href="#executables-and-launchers" id="id16">Executables and Launchers</a><ul>
<li><a class="reference internal" href="#windows-executable-launcher" id="id17">Windows Executable Launcher</a></li>
<li><a class="reference internal" href="#natural-script-launcher" id="id18">Natural Script Launcher</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tips-techniques" id="id19">Tips &amp; Techniques</a><ul>
<li><a class="reference internal" href="#multiple-python-versions" id="id20">Multiple Python Versions</a></li>
<li><a class="reference internal" href="#restricting-downloads-with-allow-hosts" id="id21">Restricting Downloads with <code class="docutils literal notranslate"><span class="pre">--allow-hosts</span></code></a></li>
<li><a class="reference internal" href="#installing-on-un-networked-machines" id="id22">Installing on Un-networked Machines</a></li>
<li><a class="reference internal" href="#packaging-others-projects-as-eggs" id="id23">Packaging Others’ Projects As Eggs</a></li>
<li><a class="reference internal" href="#creating-your-own-package-index" id="id24">Creating your own Package Index</a></li>
</ul>
</li>
<li><a class="reference internal" href="#password-protected-sites" id="id25">Password-Protected Sites</a></li>
<li><a class="reference internal" href="#using-pypirc-credentials" id="id26">Using .pypirc Credentials</a><ul>
<li><a class="reference internal" href="#controlling-build-options" id="id27">Controlling Build Options</a></li>
<li><a class="reference internal" href="#editing-and-viewing-source-packages" id="id28">Editing and Viewing Source Packages</a></li>
<li><a class="reference internal" href="#dealing-with-installation-conflicts" id="id29">Dealing with Installation Conflicts</a></li>
<li><a class="reference internal" href="#compressed-installation" id="id30">Compressed Installation</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#reference-manual" id="id31">Reference Manual</a><ul>
<li><a class="reference internal" href="#configuration-files" id="id32">Configuration Files</a></li>
<li><a class="reference internal" href="#command-line-options" id="id33">Command-Line Options</a></li>
<li><a class="reference internal" href="#custom-installation-locations" id="id34">Custom Installation Locations</a><ul>
<li><a class="reference internal" href="#use-the-user-option" id="id35">Use the “–user” option</a></li>
<li><a class="reference internal" href="#use-the-user-option-and-customize-pythonuserbase" id="id36">Use the “–user” option and customize “PYTHONUSERBASE”</a></li>
<li><a class="reference internal" href="#use-virtualenv" id="id37">Use “virtualenv”</a></li>
</ul>
</li>
<li><a class="reference internal" href="#package-index-api" id="id38">Package Index “API”</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="using-easy-install">
<h3><a class="toc-backref" href="#id7">Using “Easy Install”</a><a class="headerlink" href="#using-easy-install" title="Permalink to this headline">¶</a></h3>
<div class="section" id="installing-easy-install">
<span id="installation-instructions"></span><h4><a class="toc-backref" href="#id8">Installing “Easy Install”</a><a class="headerlink" href="#installing-easy-install" title="Permalink to this headline">¶</a></h4>
<p>Please see the <a class="reference external" href="https://pypi.org/project/setuptools/">setuptools PyPI page</a>
for download links and basic installation instructions for each of the
supported platforms.</p>
<p>You will need at least Python 3.5 or 2.7.  An <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> script will be
installed in the normal location for Python scripts on your platform.</p>
<p>Note that the instructions on the setuptools PyPI page assume that you are
are installing to Python’s primary <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory.  If this is
not the case, you should consult the section below on <a class="reference internal" href="#custom-installation-locations">Custom Installation
Locations</a> before installing.  (And, on Windows, you should not use the
<code class="docutils literal notranslate"><span class="pre">.exe</span></code> installer when installing to an alternate location.)</p>
<p>Note that <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> normally works by downloading files from the
internet.  If you are behind an NTLM-based firewall that prevents Python
programs from accessing the net directly, you may wish to first install and use
the <a class="reference external" href="http://ntlmaps.sf.net/">APS proxy server</a>, which lets you get past such
firewalls in the same way that your web browser(s) do.</p>
<p>(Alternately, if you do not wish easy_install to actually download anything, you
can restrict it from doing so with the <code class="docutils literal notranslate"><span class="pre">--allow-hosts</span></code> option; see the
sections on <a class="reference internal" href="#restricting-downloads-with-allow-hosts">restricting downloads with –allow-hosts</a> and <a class="reference internal" href="#command-line-options">command-line
options</a> for more details.)</p>
<div class="section" id="troubleshooting">
<h5><a class="toc-backref" href="#id9">Troubleshooting</a><a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h5>
<p>If EasyInstall/setuptools appears to install correctly, and you can run the
<code class="docutils literal notranslate"><span class="pre">easy_install</span></code> command but it fails with an <code class="docutils literal notranslate"><span class="pre">ImportError</span></code>, the most likely
cause is that you installed to a location other than <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>,
without taking any of the steps described in the <a class="reference internal" href="#custom-installation-locations">Custom Installation
Locations</a> section below.  Please see that section and follow the steps to
make sure that your custom location will work correctly.  Then re-install.</p>
<p>Similarly, if you can run <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>, and it appears to be installing
packages, but then you can’t import them, the most likely issue is that you
installed EasyInstall correctly but are using it to install packages to a
non-standard location that hasn’t been properly prepared.  Again, see the
section on <a class="reference internal" href="#custom-installation-locations">Custom Installation Locations</a> for more details.</p>
</div>
<div class="section" id="windows-notes">
<h5><a class="toc-backref" href="#id10">Windows Notes</a><a class="headerlink" href="#windows-notes" title="Permalink to this headline">¶</a></h5>
<p>Installing setuptools will provide an <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> command according to
the techniques described in <a class="reference internal" href="#executables-and-launchers">Executables and Launchers</a>. If the
<code class="docutils literal notranslate"><span class="pre">easy_install</span></code> command is not available after installation, that section
provides details on how to configure Windows to make the commands available.</p>
</div>
</div>
<div class="section" id="downloading-and-installing-a-package">
<h4><a class="toc-backref" href="#id11">Downloading and Installing a Package</a><a class="headerlink" href="#downloading-and-installing-a-package" title="Permalink to this headline">¶</a></h4>
<p>For basic use of <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>, you need only supply the filename or URL of
a source distribution or .egg file (<a class="reference external" href="http://peak.telecommunity.com/DevCenter/PythonEggs">Python Egg</a>).</p>
<p><strong>Example 1</strong>. Install a package by name, searching PyPI for the latest
version, and automatically downloading, building, and installing it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="n">SQLObject</span>
</pre></div>
</div>
<p><strong>Example 2</strong>. Install or upgrade a package by name and version by finding
links on a given “download page”:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">-</span><span class="n">f</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">pythonpaste</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">package_index</span><span class="o">.</span><span class="n">html</span> <span class="n">SQLObject</span>
</pre></div>
</div>
<p><strong>Example 3</strong>. Download a source distribution from a specified URL,
automatically building and installing it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">MyPackage</span><span class="o">-</span><span class="mf">1.2</span><span class="o">.</span><span class="mf">3.</span><span class="n">tgz</span>
</pre></div>
</div>
<p><strong>Example 4</strong>. Install an already-downloaded .egg file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">/</span><span class="n">my_downloads</span><span class="o">/</span><span class="n">OtherPackage</span><span class="o">-</span><span class="mf">3.2</span><span class="o">.</span><span class="mi">1</span><span class="o">-</span><span class="n">py2</span><span class="o">.</span><span class="mf">3.</span><span class="n">egg</span>
</pre></div>
</div>
<p><strong>Example 5</strong>.  Upgrade an already-installed package to the latest version
listed on PyPI:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">PyProtocols</span>
</pre></div>
</div>
<p><strong>Example 6</strong>.  Install a source distribution that’s already downloaded and
extracted in the current directory (New in 0.5a9):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">.</span>
</pre></div>
</div>
<p><strong>Example 7</strong>.  (New in 0.6a1) Find a source distribution or Subversion
checkout URL for a package, and extract it or check it out to
<code class="docutils literal notranslate"><span class="pre">~/projects/sqlobject</span></code> (the name will always be in all-lowercase), where it
can be examined or edited.  (The package will not be installed, but it can
easily be installed with <code class="docutils literal notranslate"><span class="pre">easy_install</span> <span class="pre">~/projects/sqlobject</span></code>.  See <a class="reference internal" href="#editing-and-viewing-source-packages">Editing
and Viewing Source Packages</a> below for more info.):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">--</span><span class="n">editable</span> <span class="o">--</span><span class="n">build</span><span class="o">-</span><span class="n">directory</span> <span class="o">~/</span><span class="n">projects</span> <span class="n">SQLObject</span>
</pre></div>
</div>
<p><strong>Example 7</strong>. (New in 0.6.11) Install a distribution within your home dir:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">--</span><span class="n">user</span> <span class="n">SQLAlchemy</span>
</pre></div>
</div>
<p>Easy Install accepts URLs, filenames, PyPI package names (i.e., <code class="docutils literal notranslate"><span class="pre">distutils</span></code>
“distribution” names), and package+version specifiers.  In each case, it will
attempt to locate the latest available version that meets your criteria.</p>
<p>When downloading or processing downloaded files, Easy Install recognizes
distutils source distribution files with extensions of .tgz, .tar, .tar.gz,
.tar.bz2, or .zip.  And of course it handles already-built .egg
distributions as well as <code class="docutils literal notranslate"><span class="pre">.win32.exe</span></code> installers built using distutils.</p>
<p>By default, packages are installed to the running Python installation’s
<code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory, unless you provide the <code class="docutils literal notranslate"><span class="pre">-d</span></code> or <code class="docutils literal notranslate"><span class="pre">--install-dir</span></code>
option to specify an alternative directory, or specify an alternate location
using distutils configuration files.  (See <a class="reference internal" href="#configuration-files">Configuration Files</a>, below.)</p>
<p>By default, any scripts included with the package are installed to the running
Python installation’s standard script installation location.  However, if you
specify an installation directory via the command line or a config file, then
the default directory for installing scripts will be the same as the package
installation directory, to ensure that the script will have access to the
installed package.  You can override this using the <code class="docutils literal notranslate"><span class="pre">-s</span></code> or <code class="docutils literal notranslate"><span class="pre">--script-dir</span></code>
option.</p>
<p>Installed packages are added to an <code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> file in the install
directory, so that Python will always use the most-recently-installed version
of the package.  If you would like to be able to select which version to use at
runtime, you should use the <code class="docutils literal notranslate"><span class="pre">-m</span></code> or <code class="docutils literal notranslate"><span class="pre">--multi-version</span></code> option.</p>
</div>
<div class="section" id="upgrading-a-package">
<h4><a class="toc-backref" href="#id12">Upgrading a Package</a><a class="headerlink" href="#upgrading-a-package" title="Permalink to this headline">¶</a></h4>
<p>You don’t need to do anything special to upgrade a package: just install the
new version, either by requesting a specific version, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="s2">&quot;SomePackage==2.0&quot;</span>
</pre></div>
</div>
<p>a version greater than the one you have now:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="s2">&quot;SomePackage&gt;2.0&quot;</span>
</pre></div>
</div>
<p>using the upgrade flag, to find the latest available version on PyPI:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">SomePackage</span>
</pre></div>
</div>
<p>or by using a download page, direct download URL, or package filename:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">-</span><span class="n">f</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">downloads</span> <span class="n">ExamplePackage</span>

<span class="n">easy_install</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">downloads</span><span class="o">/</span><span class="n">ExamplePackage</span><span class="o">-</span><span class="mf">2.0</span><span class="o">-</span><span class="n">py2</span><span class="o">.</span><span class="mf">4.</span><span class="n">egg</span>

<span class="n">easy_install</span> <span class="n">my_downloads</span><span class="o">/</span><span class="n">ExamplePackage</span><span class="o">-</span><span class="mf">2.0</span><span class="o">.</span><span class="n">tgz</span>
</pre></div>
</div>
<p>If you’re using <code class="docutils literal notranslate"><span class="pre">-m</span></code> or <code class="docutils literal notranslate"><span class="pre">--multi-version</span></code> , using the <code class="docutils literal notranslate"><span class="pre">require()</span></code>
function at runtime automatically selects the newest installed version of a
package that meets your version criteria.  So, installing a newer version is
the only step needed to upgrade such packages.</p>
<p>If you’re installing to a directory on PYTHONPATH, or a configured “site”
directory (and not using <code class="docutils literal notranslate"><span class="pre">-m</span></code>), installing a package automatically replaces
any previous version in the <code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> file, so that Python will
import the most-recently installed version by default.  So, again, installing
the newer version is the only upgrade step needed.</p>
<p>If you haven’t suppressed script installation (using <code class="docutils literal notranslate"><span class="pre">--exclude-scripts</span></code> or
<code class="docutils literal notranslate"><span class="pre">-x</span></code>), then the upgraded version’s scripts will be installed, and they will
be automatically patched to <code class="docutils literal notranslate"><span class="pre">require()</span></code> the corresponding version of the
package, so that you can use them even if they are installed in multi-version
mode.</p>
<p><code class="docutils literal notranslate"><span class="pre">easy_install</span></code> never actually deletes packages (unless you’re installing a
package with the same name and version number as an existing package), so if
you want to get rid of older versions of a package, please see <a class="reference internal" href="#uninstalling-packages">Uninstalling
Packages</a>, below.</p>
</div>
<div class="section" id="changing-the-active-version">
<h4><a class="toc-backref" href="#id13">Changing the Active Version</a><a class="headerlink" href="#changing-the-active-version" title="Permalink to this headline">¶</a></h4>
<p>If you’ve upgraded a package, but need to revert to a previously-installed
version, you can do so like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="n">PackageName</span><span class="o">==</span><span class="mf">1.2</span><span class="o">.</span><span class="mi">3</span>
</pre></div>
</div>
<p>Where <code class="docutils literal notranslate"><span class="pre">1.2.3</span></code> is replaced by the exact version number you wish to switch to.
If a package matching the requested name and version is not already installed
in a directory on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, it will be located via PyPI and installed.</p>
<p>If you’d like to switch to the latest installed version of <code class="docutils literal notranslate"><span class="pre">PackageName</span></code>, you
can do so like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="n">PackageName</span>
</pre></div>
</div>
<p>This will activate the latest installed version.  (Note: if you have set any
<code class="docutils literal notranslate"><span class="pre">find_links</span></code> via distutils configuration files, those download pages will be
checked for the latest available version of the package, and it will be
downloaded and installed if it is newer than your current version.)</p>
<p>Note that changing the active version of a package will install the newly
active version’s scripts, unless the <code class="docutils literal notranslate"><span class="pre">--exclude-scripts</span></code> or <code class="docutils literal notranslate"><span class="pre">-x</span></code> option is
specified.</p>
</div>
<div class="section" id="uninstalling-packages">
<h4><a class="toc-backref" href="#id14">Uninstalling Packages</a><a class="headerlink" href="#uninstalling-packages" title="Permalink to this headline">¶</a></h4>
<p>If you have replaced a package with another version, then you can just delete
the package(s) you don’t need by deleting the PackageName-versioninfo.egg file
or directory (found in the installation directory).</p>
<p>If you want to delete the currently installed version of a package (or all
versions of a package), you should first run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">-</span><span class="n">m</span> <span class="n">PackageName</span>
</pre></div>
</div>
<p>This will ensure that Python doesn’t continue to search for a package you’re
planning to remove. After you’ve done this, you can safely delete the .egg
files or directories, along with any scripts you wish to remove.</p>
</div>
<div class="section" id="managing-scripts">
<h4><a class="toc-backref" href="#id15">Managing Scripts</a><a class="headerlink" href="#managing-scripts" title="Permalink to this headline">¶</a></h4>
<p>Whenever you install, upgrade, or change versions of a package, EasyInstall
automatically installs the scripts for the selected package version, unless
you tell it not to with <code class="docutils literal notranslate"><span class="pre">-x</span></code> or <code class="docutils literal notranslate"><span class="pre">--exclude-scripts</span></code>.  If any scripts in
the script directory have the same name, they are overwritten.</p>
<p>Thus, you do not normally need to manually delete scripts for older versions of
a package, unless the newer version of the package does not include a script
of the same name.  However, if you are completely uninstalling a package, you
may wish to manually delete its scripts.</p>
<p>EasyInstall’s default behavior means that you can normally only run scripts
from one version of a package at a time.  If you want to keep multiple versions
of a script available, however, you can simply use the <code class="docutils literal notranslate"><span class="pre">--multi-version</span></code> or
<code class="docutils literal notranslate"><span class="pre">-m</span></code> option, and rename the scripts that EasyInstall creates.  This works
because EasyInstall installs scripts as short code stubs that <code class="docutils literal notranslate"><span class="pre">require()</span></code> the
matching version of the package the script came from, so renaming the script
has no effect on what it executes.</p>
<p>For example, suppose you want to use two versions of the <code class="docutils literal notranslate"><span class="pre">rst2html</span></code> tool
provided by the <a class="reference external" href="http://docutils.sf.net/">docutils</a> package.  You might
first install one version:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">-</span><span class="n">m</span> <span class="n">docutils</span><span class="o">==</span><span class="mf">0.3</span><span class="o">.</span><span class="mi">9</span>
</pre></div>
</div>
<p>then rename the <code class="docutils literal notranslate"><span class="pre">rst2html.py</span></code> to <code class="docutils literal notranslate"><span class="pre">r2h_039</span></code>, and install another version:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">-</span><span class="n">m</span> <span class="n">docutils</span><span class="o">==</span><span class="mf">0.3</span><span class="o">.</span><span class="mi">10</span>
</pre></div>
</div>
<p>This will create another <code class="docutils literal notranslate"><span class="pre">rst2html.py</span></code> script, this one using docutils
version 0.3.10 instead of 0.3.9.  You now have two scripts, each using a
different version of the package.  (Notice that we used <code class="docutils literal notranslate"><span class="pre">-m</span></code> for both
installations, so that Python won’t lock us out of using anything but the most
recently-installed version of the package.)</p>
</div>
<div class="section" id="executables-and-launchers">
<h4><a class="toc-backref" href="#id16">Executables and Launchers</a><a class="headerlink" href="#executables-and-launchers" title="Permalink to this headline">¶</a></h4>
<p>On Unix systems, scripts are installed with as natural files with a “#!”
header and no extension and they launch under the Python version indicated in
the header.</p>
<p>On Windows, there is no mechanism to “execute” files without extensions, so
EasyInstall provides two techniques to mirror the Unix behavior. The behavior
is indicated by the SETUPTOOLS_LAUNCHER environment variable, which may be
“executable” (default) or “natural”.</p>
<p>Regardless of the technique used, the script(s) will be installed to a Scripts
directory (by default in the Python installation directory). It is recommended
for EasyInstall that you ensure this directory is in the PATH environment
variable. The easiest way to ensure the Scripts directory is in the PATH is
to run <code class="docutils literal notranslate"><span class="pre">Tools\Scripts\win_add2path.py</span></code> from the Python directory.</p>
<p>Note that instead of changing your <code class="docutils literal notranslate"><span class="pre">PATH</span></code> to include the Python scripts
directory, you can also retarget the installation location for scripts so they
go on a directory that’s already on the <code class="docutils literal notranslate"><span class="pre">PATH</span></code>.  For more information see
<a class="reference internal" href="#command-line-options">Command-Line Options</a> and <a class="reference internal" href="#configuration-files">Configuration Files</a>.  During installation,
pass command line options (such as <code class="docutils literal notranslate"><span class="pre">--script-dir</span></code>) to control where
scripts will be installed.</p>
<div class="section" id="windows-executable-launcher">
<h5><a class="toc-backref" href="#id17">Windows Executable Launcher</a><a class="headerlink" href="#windows-executable-launcher" title="Permalink to this headline">¶</a></h5>
<p>If the “executable” launcher is used, EasyInstall will create a ‘.exe’
launcher of the same name beside each installed script (including
<code class="docutils literal notranslate"><span class="pre">easy_install</span></code> itself). These small .exe files launch the script of the
same name using the Python version indicated in the ‘#!’ header.</p>
<p>This behavior is currently default. To force
the use of executable launchers, set <code class="docutils literal notranslate"><span class="pre">SETUPTOOLS_LAUNCHER</span></code> to “executable”.</p>
</div>
<div class="section" id="natural-script-launcher">
<h5><a class="toc-backref" href="#id18">Natural Script Launcher</a><a class="headerlink" href="#natural-script-launcher" title="Permalink to this headline">¶</a></h5>
<p>EasyInstall also supports deferring to an external launcher such as
<a class="reference external" href="https://bitbucket.org/pypa/pylauncher">pylauncher</a> for launching scripts.
Enable this experimental functionality by setting the
<code class="docutils literal notranslate"><span class="pre">SETUPTOOLS_LAUNCHER</span></code> environment variable to “natural”. EasyInstall will
then install scripts as simple
scripts with a .pya (or .pyw) extension appended. If these extensions are
associated with the pylauncher and listed in the PATHEXT environment variable,
these scripts can then be invoked simply and directly just like any other
executable. This behavior may become default in a future version.</p>
<p>EasyInstall uses the .pya extension instead of simply
the typical ‘.py’ extension. This distinct extension is necessary to prevent
Python
from treating the scripts as importable modules (where name conflicts exist).
Current releases of pylauncher do not yet associate with .pya files by
default, but future versions should do so.</p>
</div>
</div>
<div class="section" id="tips-techniques">
<h4><a class="toc-backref" href="#id19">Tips &amp; Techniques</a><a class="headerlink" href="#tips-techniques" title="Permalink to this headline">¶</a></h4>
<div class="section" id="multiple-python-versions">
<h5><a class="toc-backref" href="#id20">Multiple Python Versions</a><a class="headerlink" href="#multiple-python-versions" title="Permalink to this headline">¶</a></h5>
<p>EasyInstall installs itself under two names:
<code class="docutils literal notranslate"><span class="pre">easy_install</span></code> and <code class="docutils literal notranslate"><span class="pre">easy_install-N.N</span></code>, where <code class="docutils literal notranslate"><span class="pre">N.N</span></code> is the Python version
used to install it.  Thus, if you install EasyInstall for both Python 3.2 and
2.7, you can use the <code class="docutils literal notranslate"><span class="pre">easy_install-3.2</span></code> or <code class="docutils literal notranslate"><span class="pre">easy_install-2.7</span></code> scripts to
install packages for the respective Python version.</p>
<p>Setuptools also supplies easy_install as a runnable module which may be
invoked using <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">easy_install</span></code> for any Python with Setuptools
installed.</p>
</div>
<div class="section" id="restricting-downloads-with-allow-hosts">
<h5><a class="toc-backref" href="#id21">Restricting Downloads with <code class="docutils literal notranslate"><span class="pre">--allow-hosts</span></code></a><a class="headerlink" href="#restricting-downloads-with-allow-hosts" title="Permalink to this headline">¶</a></h5>
<p>You can use the <code class="docutils literal notranslate"><span class="pre">--allow-hosts</span></code> (<code class="docutils literal notranslate"><span class="pre">-H</span></code>) option to restrict what domains
EasyInstall will look for links and downloads on.  <code class="docutils literal notranslate"><span class="pre">--allow-hosts=None</span></code>
prevents downloading altogether.  You can also use wildcards, for example
to restrict downloading to hosts in your own intranet.  See the section below
on <a class="reference internal" href="#command-line-options">Command-Line Options</a> for more details on the <code class="docutils literal notranslate"><span class="pre">--allow-hosts</span></code> option.</p>
<p>By default, there are no host restrictions in effect, but you can change this
default by editing the appropriate <a class="reference internal" href="#configuration-files">configuration files</a> and adding:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[easy_install]</span>
<span class="na">allow_hosts</span> <span class="o">=</span> <span class="s">*.myintranet.example.com,*.python.org</span>
</pre></div>
</div>
<p>The above example would then allow downloads only from hosts in the
<code class="docutils literal notranslate"><span class="pre">python.org</span></code> and <code class="docutils literal notranslate"><span class="pre">myintranet.example.com</span></code> domains, unless overridden on the
command line.</p>
</div>
<div class="section" id="installing-on-un-networked-machines">
<h5><a class="toc-backref" href="#id22">Installing on Un-networked Machines</a><a class="headerlink" href="#installing-on-un-networked-machines" title="Permalink to this headline">¶</a></h5>
<p>Just copy the eggs or source packages you need to a directory on the target
machine, then use the <code class="docutils literal notranslate"><span class="pre">-f</span></code> or <code class="docutils literal notranslate"><span class="pre">--find-links</span></code> option to specify that
directory’s location.  For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">-</span><span class="n">H</span> <span class="kc">None</span> <span class="o">-</span><span class="n">f</span> <span class="n">somedir</span> <span class="n">SomePackage</span>
</pre></div>
</div>
<p>will attempt to install SomePackage using only eggs and source packages found
in <code class="docutils literal notranslate"><span class="pre">somedir</span></code> and disallowing all remote access.  You should of course make
sure you have all of SomePackage’s dependencies available in somedir.</p>
<p>If you have another machine of the same operating system and library versions
(or if the packages aren’t platform-specific), you can create the directory of
eggs using a command like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">-</span><span class="n">zmaxd</span> <span class="n">somedir</span> <span class="n">SomePackage</span>
</pre></div>
</div>
<p>This will tell EasyInstall to put zipped eggs or source packages for
SomePackage and all its dependencies into <code class="docutils literal notranslate"><span class="pre">somedir</span></code>, without creating any
scripts or .pth files.  You can then copy the contents of <code class="docutils literal notranslate"><span class="pre">somedir</span></code> to the
target machine.  (<code class="docutils literal notranslate"><span class="pre">-z</span></code> means zipped eggs, <code class="docutils literal notranslate"><span class="pre">-m</span></code> means multi-version, which
prevents .pth files from being used, <code class="docutils literal notranslate"><span class="pre">-a</span></code> means to copy all the eggs needed,
even if they’re installed elsewhere on the machine, and <code class="docutils literal notranslate"><span class="pre">-d</span></code> indicates the
directory to place the eggs in.)</p>
<p>You can also build the eggs from local development packages that were installed
with the <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code> command, by including the <code class="docutils literal notranslate"><span class="pre">-l</span></code> option, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">-</span><span class="n">zmaxld</span> <span class="n">somedir</span> <span class="n">SomePackage</span>
</pre></div>
</div>
<p>This will use locally-available source distributions to build the eggs.</p>
</div>
<div class="section" id="packaging-others-projects-as-eggs">
<h5><a class="toc-backref" href="#id23">Packaging Others’ Projects As Eggs</a><a class="headerlink" href="#packaging-others-projects-as-eggs" title="Permalink to this headline">¶</a></h5>
<p>Need to distribute a package that isn’t published in egg form?  You can use
EasyInstall to build eggs for a project.  You’ll want to use the <code class="docutils literal notranslate"><span class="pre">--zip-ok</span></code>,
<code class="docutils literal notranslate"><span class="pre">--exclude-scripts</span></code>, and possibly <code class="docutils literal notranslate"><span class="pre">--no-deps</span></code> options (<code class="docutils literal notranslate"><span class="pre">-z</span></code>, <code class="docutils literal notranslate"><span class="pre">-x</span></code> and
<code class="docutils literal notranslate"><span class="pre">-N</span></code>, respectively).  Use <code class="docutils literal notranslate"><span class="pre">-d</span></code> or <code class="docutils literal notranslate"><span class="pre">--install-dir</span></code> to specify the location
where you’d like the eggs placed.  By placing them in a directory that is
published to the web, you can then make the eggs available for download, either
in an intranet or to the internet at large.</p>
<p>If someone distributes a package in the form of a single <code class="docutils literal notranslate"><span class="pre">.py</span></code> file, you can
wrap it in an egg by tacking an <code class="docutils literal notranslate"><span class="pre">#egg=name-version</span></code> suffix on the file’s URL.
So, something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">-</span><span class="n">f</span> <span class="s2">&quot;http://some.example.com/downloads/foo.py#egg=foo-1.0&quot;</span> <span class="n">foo</span>
</pre></div>
</div>
<p>will install the package as an egg, and this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">-</span><span class="n">zmaxd</span><span class="o">.</span> \
    <span class="o">-</span><span class="n">f</span> <span class="s2">&quot;http://some.example.com/downloads/foo.py#egg=foo-1.0&quot;</span> <span class="n">foo</span>
</pre></div>
</div>
<p>will create a <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file in the current directory.</p>
</div>
<div class="section" id="creating-your-own-package-index">
<h5><a class="toc-backref" href="#id24">Creating your own Package Index</a><a class="headerlink" href="#creating-your-own-package-index" title="Permalink to this headline">¶</a></h5>
<p>In addition to local directories and the Python Package Index, EasyInstall can
find download links on most any web page whose URL is given to the <code class="docutils literal notranslate"><span class="pre">-f</span></code>
(<code class="docutils literal notranslate"><span class="pre">--find-links</span></code>) option.  In the simplest case, you can simply have a web
page with links to eggs or Python source packages, even an automatically
generated directory listing (such as the Apache web server provides).</p>
<p>If you are setting up an intranet site for package downloads, you may want to
configure the target machines to use your download site by default, adding
something like this to their <a class="reference internal" href="#configuration-files">configuration files</a>:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[easy_install]</span>
<span class="na">find_links</span> <span class="o">=</span> <span class="s">http://mypackages.example.com/somedir/</span>
<span class="s">             http://turbogears.org/download/</span>
<span class="s">             http://peak.telecommunity.com/dist/</span>
</pre></div>
</div>
<p>As you can see, you can list multiple URLs separated by whitespace, continuing
on multiple lines if necessary (as long as the subsequent lines are indented.</p>
<p>If you are more ambitious, you can also create an entirely custom package index
or PyPI mirror.  See the <code class="docutils literal notranslate"><span class="pre">--index-url</span></code> option under <a class="reference internal" href="#command-line-options">Command-Line Options</a>,
below, and also the section on <a class="reference internal" href="#package-index-api">Package Index “API”</a>.</p>
</div>
</div>
<div class="section" id="password-protected-sites">
<h4><a class="toc-backref" href="#id25">Password-Protected Sites</a><a class="headerlink" href="#password-protected-sites" title="Permalink to this headline">¶</a></h4>
<p>If a site you want to download from is password-protected using HTTP “Basic”
authentication, you can specify your credentials in the URL, like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">some_userid</span><span class="p">:</span><span class="n">some_password</span><span class="nd">@some</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">some_path</span><span class="o">/</span>
</pre></div>
</div>
<p>You can do this with both index page URLs and direct download URLs.  As long
as any HTML pages read by easy_install use <em>relative</em> links to point to the
downloads, the same user ID and password will be used to do the downloading.</p>
</div>
<div class="section" id="using-pypirc-credentials">
<h4><a class="toc-backref" href="#id26">Using .pypirc Credentials</a><a class="headerlink" href="#using-pypirc-credentials" title="Permalink to this headline">¶</a></h4>
<p>In additional to supplying credentials in the URL, <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> will also
honor credentials if present in the .pypirc file. Teams maintaining a private
repository of packages may already have defined access credentials for
uploading packages according to the distutils documentation. <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>
will attempt to honor those if present. Refer to the distutils documentation
for Python 2.5 or later for details on the syntax.</p>
<div class="section" id="controlling-build-options">
<h5><a class="toc-backref" href="#id27">Controlling Build Options</a><a class="headerlink" href="#controlling-build-options" title="Permalink to this headline">¶</a></h5>
<p>EasyInstall respects standard distutils <a class="reference internal" href="#configuration-files">Configuration Files</a>, so you can use
them to configure build options for packages that it installs from source.  For
example, if you are on Windows using the MinGW compiler, you can configure the
default compiler by putting something like this:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[build]</span>
<span class="na">compiler</span> <span class="o">=</span> <span class="s">mingw32</span>
</pre></div>
</div>
<p>into the appropriate distutils configuration file.  In fact, since this is just
normal distutils configuration, it will affect any builds using that config
file, not just ones done by EasyInstall.  For example, if you add those lines
to <code class="docutils literal notranslate"><span class="pre">distutils.cfg</span></code> in the <code class="docutils literal notranslate"><span class="pre">distutils</span></code> package directory, it will be the
default compiler for <em>all</em> packages you build.  See <a class="reference internal" href="#configuration-files">Configuration Files</a>
below for a list of the standard configuration file locations, and links to
more documentation on using distutils configuration files.</p>
</div>
<div class="section" id="editing-and-viewing-source-packages">
<h5><a class="toc-backref" href="#id28">Editing and Viewing Source Packages</a><a class="headerlink" href="#editing-and-viewing-source-packages" title="Permalink to this headline">¶</a></h5>
<p>Sometimes a package’s source distribution  contains additional documentation,
examples, configuration files, etc., that are not part of its actual code.  If
you want to be able to examine these files, you can use the <code class="docutils literal notranslate"><span class="pre">--editable</span></code>
option to EasyInstall, and EasyInstall will look for a source distribution
or Subversion URL for the package, then download and extract it or check it out
as a subdirectory of the <code class="docutils literal notranslate"><span class="pre">--build-directory</span></code> you specify.  If you then wish
to install the package after editing or configuring it, you can do so by
rerunning EasyInstall with that directory as the target.</p>
<p>Note that using <code class="docutils literal notranslate"><span class="pre">--editable</span></code> stops EasyInstall from actually building or
installing the package; it just finds, obtains, and possibly unpacks it for
you.  This allows you to make changes to the package if necessary, and to
either install it in development mode using <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code> (if the
package uses setuptools, that is), or by running <code class="docutils literal notranslate"><span class="pre">easy_install</span> <span class="pre">projectdir</span></code>
(where <code class="docutils literal notranslate"><span class="pre">projectdir</span></code> is the subdirectory EasyInstall created for the
downloaded package.</p>
<p>In order to use <code class="docutils literal notranslate"><span class="pre">--editable</span></code> (<code class="docutils literal notranslate"><span class="pre">-e</span></code> for short), you <em>must</em> also supply a
<code class="docutils literal notranslate"><span class="pre">--build-directory</span></code> (<code class="docutils literal notranslate"><span class="pre">-b</span></code> for short).  The project will be placed in a
subdirectory of the build directory.  The subdirectory will have the same
name as the project itself, but in all-lowercase.  If a file or directory of
that name already exists, EasyInstall will print an error message and exit.</p>
<p>Also, when using <code class="docutils literal notranslate"><span class="pre">--editable</span></code>, you cannot use URLs or filenames as arguments.
You <em>must</em> specify project names (and optional version requirements) so that
EasyInstall knows what directory name(s) to create.  If you need to force
EasyInstall to use a particular URL or filename, you should specify it as a
<code class="docutils literal notranslate"><span class="pre">--find-links</span></code> item (<code class="docutils literal notranslate"><span class="pre">-f</span></code> for short), and then also specify
the project name, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>easy_install -eb ~/projects \
 -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \
 ctypes==0.9.6
</pre></div>
</div>
</div>
<div class="section" id="dealing-with-installation-conflicts">
<h5><a class="toc-backref" href="#id29">Dealing with Installation Conflicts</a><a class="headerlink" href="#dealing-with-installation-conflicts" title="Permalink to this headline">¶</a></h5>
<p>(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that
people using older versions of EasyInstall can consult it.  As of version
0.6a11, installation conflicts are handled automatically without deleting the
old or system-installed packages, and without ignoring the issue.  Instead,
eggs are automatically shifted to the front of <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> using special
code added to the <code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> file.  So, if you are using version
0.6a11 or better of setuptools, you do not need to worry about conflicts,
and the following issues do not apply to you.)</p>
<p>EasyInstall installs distributions in a “managed” way, such that each
distribution can be independently activated or deactivated on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>.
However, packages that were not installed by EasyInstall are “unmanaged”,
in that they usually live all in one directory and cannot be independently
activated or deactivated.</p>
<p>As a result, if you are using EasyInstall to upgrade an existing package, or
to install a package with the same name as an existing package, EasyInstall
will warn you of the conflict.  (This is an improvement over <code class="docutils literal notranslate"><span class="pre">setup.py</span>
<span class="pre">install</span></code>, because the <code class="docutils literal notranslate"><span class="pre">distutils</span></code> just install new packages on top of old
ones, possibly combining two unrelated packages or leaving behind modules that
have been deleted in the newer version of the package.)</p>
<p>EasyInstall will stop the installation if it detects a conflict
between an existing, “unmanaged” package, and a module or package in any of
the distributions you’re installing.  It will display a list of all of the
existing files and directories that would need to be deleted for the new
package to be able to function correctly.  To proceed, you must manually
delete these conflicting files and directories and re-run EasyInstall.</p>
<p>Of course, once you’ve replaced all of your existing “unmanaged” packages with
versions managed by EasyInstall, you won’t have any more conflicts to worry
about!</p>
</div>
<div class="section" id="compressed-installation">
<h5><a class="toc-backref" href="#id30">Compressed Installation</a><a class="headerlink" href="#compressed-installation" title="Permalink to this headline">¶</a></h5>
<p>EasyInstall tries to install packages in zipped form, if it can.  Zipping
packages can improve Python’s overall import performance if you’re not using
the <code class="docutils literal notranslate"><span class="pre">--multi-version</span></code> option, because Python processes zipfile entries on
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> much faster than it does directories.</p>
<p>As of version 0.5a9, EasyInstall analyzes packages to determine whether they
can be safely installed as a zipfile, and then acts on its analysis.  (Previous
versions would not install a package as a zipfile unless you used the
<code class="docutils literal notranslate"><span class="pre">--zip-ok</span></code> option.)</p>
<p>The current analysis approach is fairly conservative; it currently looks for:</p>
<blockquote>
<div><ul class="simple">
<li>Any use of the <code class="docutils literal notranslate"><span class="pre">__file__</span></code> or <code class="docutils literal notranslate"><span class="pre">__path__</span></code> variables (which should be
replaced with <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> API calls)</li>
<li>Possible use of <code class="docutils literal notranslate"><span class="pre">inspect</span></code> functions that expect to manipulate source files
(e.g. <code class="docutils literal notranslate"><span class="pre">inspect.getsource()</span></code>)</li>
<li>Top-level modules that might be scripts used with <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span></code> (Python 2.4)</li>
</ul>
</div></blockquote>
<p>If any of the above are found in the package being installed, EasyInstall will
assume that the package cannot be safely run from a zipfile, and unzip it to
a directory instead.  You can override this analysis with the <code class="docutils literal notranslate"><span class="pre">-zip-ok</span></code> flag,
which will tell EasyInstall to install the package as a zipfile anyway.  Or,
you can use the <code class="docutils literal notranslate"><span class="pre">--always-unzip</span></code> flag, in which case EasyInstall will always
unzip, even if its analysis says the package is safe to run as a zipfile.</p>
<p>Normally, however, it is simplest to let EasyInstall handle the determination
of whether to zip or unzip, and only specify overrides when needed to work
around a problem.  If you find you need to override EasyInstall’s guesses, you
may want to contact the package author and the EasyInstall maintainers, so that
they can make appropriate changes in future versions.</p>
<p>(Note: If a package uses <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> in its setup script, the package author
has the option to declare the package safe or unsafe for zipped usage via the
<code class="docutils literal notranslate"><span class="pre">zip_safe</span></code> argument to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>.  If the package author makes such a
declaration, EasyInstall believes the package’s author and does not perform its
own analysis.  However, your command-line option, if any, will still override
the package author’s choice.)</p>
</div>
</div>
</div>
<div class="section" id="reference-manual">
<h3><a class="toc-backref" href="#id31">Reference Manual</a><a class="headerlink" href="#reference-manual" title="Permalink to this headline">¶</a></h3>
<div class="section" id="configuration-files">
<h4><a class="toc-backref" href="#id32">Configuration Files</a><a class="headerlink" href="#configuration-files" title="Permalink to this headline">¶</a></h4>
<p>(New in 0.4a2)</p>
<p>You may specify default options for EasyInstall using the standard
distutils configuration files, under the command heading <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>.
EasyInstall will look first for a <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> file in the current directory,
then a <code class="docutils literal notranslate"><span class="pre">~/.pydistutils.cfg</span></code> or <code class="docutils literal notranslate"><span class="pre">$HOME\\pydistutils.cfg</span></code> (on Unix-like OSes
and Windows, respectively), and finally a <code class="docutils literal notranslate"><span class="pre">distutils.cfg</span></code> file in the
<code class="docutils literal notranslate"><span class="pre">distutils</span></code> package directory.  Here’s a simple example:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[easy_install]</span>

<span class="c1"># set the default location to install packages</span>
<span class="na">install_dir</span> <span class="o">=</span> <span class="s">/home/me/lib/python</span>

<span class="c1"># Notice that indentation can be used to continue an option</span>
<span class="c1"># value; this is especially useful for the &quot;--find-links&quot;</span>
<span class="c1"># option, which tells easy_install to use download links on</span>
<span class="c1"># these pages before consulting PyPI:</span>
<span class="c1">#</span>
<span class="na">find_links</span> <span class="o">=</span> <span class="s">http://sqlobject.org/</span>
<span class="s">             http://peak.telecommunity.com/dist/</span>
</pre></div>
</div>
<p>In addition to accepting configuration for its own options under
<code class="docutils literal notranslate"><span class="pre">[easy_install]</span></code>, EasyInstall also respects defaults specified for other
distutils commands.  For example, if you don’t set an <code class="docutils literal notranslate"><span class="pre">install_dir</span></code> for
<code class="docutils literal notranslate"><span class="pre">[easy_install]</span></code>, but <em>have</em> set an <code class="docutils literal notranslate"><span class="pre">install_lib</span></code> for the <code class="docutils literal notranslate"><span class="pre">[install]</span></code>
command, this will become EasyInstall’s default installation directory.  Thus,
if you are already using distutils configuration files to set default install
locations, build options, etc., EasyInstall will respect your existing settings
until and unless you override them explicitly in an <code class="docutils literal notranslate"><span class="pre">[easy_install]</span></code> section.</p>
<p>For more information, see also the current Python documentation on the <a class="reference external" href="https://docs.python.org/install/index.html#inst-config-files">use and
location of distutils configuration files</a>.</p>
<p>Notice that <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> will use the <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> from the current
working directory only if it was triggered from <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> through the
<code class="docutils literal notranslate"><span class="pre">install_requires</span></code> option. The standalone command will not use that file.</p>
</div>
<div class="section" id="command-line-options">
<h4><a class="toc-backref" href="#id33">Command-Line Options</a><a class="headerlink" href="#command-line-options" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">--zip-ok,</span> <span class="pre">-z</span></code></dt>
<dd>Install all packages as zip files, even if they are marked as unsafe for
running as a zipfile.  This can be useful when EasyInstall’s analysis
of a non-setuptools package is too conservative, but keep in mind that
the package may not work correctly.  (Changed in 0.5a9; previously this
option was required in order for zipped installation to happen at all.)</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--always-unzip,</span> <span class="pre">-Z</span></code></dt>
<dd><p class="first">Don’t install any packages as zip files, even if the packages are marked
as safe for running as a zipfile.  This can be useful if a package does
something unsafe, but not in a way that EasyInstall can easily detect.
EasyInstall’s default analysis is currently very conservative, however, so
you should only use this option if you’ve had problems with a particular
package, and <em>after</em> reporting the problem to the package’s maintainer and
to the EasyInstall maintainers.</p>
<p class="last">(Note: the <code class="docutils literal notranslate"><span class="pre">-z/-Z</span></code> options only affect the installation of newly-built
or downloaded packages that are not already installed in the target
directory; if you want to convert an existing installed version from
zipped to unzipped or vice versa, you’ll need to delete the existing
version first, and re-run EasyInstall.)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--multi-version,</span> <span class="pre">-m</span></code></dt>
<dd><p class="first">“Multi-version” mode. Specifying this option prevents <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> from
adding an <code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> entry for the package being installed, and
if an entry for any version the package already exists, it will be removed
upon successful installation. In multi-version mode, no specific version of
the package is available for importing, unless you use
<code class="docutils literal notranslate"><span class="pre">pkg_resources.require()</span></code> to put it on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>. This can be as
simple as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pkg_resources</span> <span class="k">import</span> <span class="n">require</span>
<span class="n">require</span><span class="p">(</span><span class="s2">&quot;SomePackage&quot;</span><span class="p">,</span> <span class="s2">&quot;OtherPackage&quot;</span><span class="p">,</span> <span class="s2">&quot;MyPackage&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>which will put the latest installed version of the specified packages on
<code class="docutils literal notranslate"><span class="pre">sys.path</span></code> for you. (For more advanced uses, like selecting specific
versions and enabling optional dependencies, see the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> API
doc.)</p>
<p class="last">Changed in 0.6a10: this option is no longer silently enabled when
installing to a non-PYTHONPATH, non-“site” directory.  You must always
explicitly use this option if you want it to be active.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--upgrade,</span> <span class="pre">-U</span></code>   (New in 0.5a4)</dt>
<dd>By default, EasyInstall only searches online if a project/version
requirement can’t be met by distributions already installed
on sys.path or the installation directory.  However, if you supply the
<code class="docutils literal notranslate"><span class="pre">--upgrade</span></code> or <code class="docutils literal notranslate"><span class="pre">-U</span></code> flag, EasyInstall will always check the package
index and <code class="docutils literal notranslate"><span class="pre">--find-links</span></code> URLs before selecting a version to install.  In
this way, you can force EasyInstall to use the latest available version of
any package it installs (subject to any version requirements that might
exclude such later versions).</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--install-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></code></dt>
<dd><p class="first">Set the installation directory. It is up to you to ensure that this
directory is on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> at runtime, and to use
<code class="docutils literal notranslate"><span class="pre">pkg_resources.require()</span></code> to enable the installed package(s) that you
need.</p>
<p class="last">(New in 0.4a2) If this option is not directly specified on the command line
or in a distutils configuration file, the distutils default installation
location is used.  Normally, this would be the <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory,
but if you are using distutils configuration files, setting things like
<code class="docutils literal notranslate"><span class="pre">prefix</span></code> or <code class="docutils literal notranslate"><span class="pre">install_lib</span></code>, then those settings are taken into
account when computing the default installation directory, as is the
<code class="docutils literal notranslate"><span class="pre">--prefix</span></code> option.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--script-dir=DIR,</span> <span class="pre">-s</span> <span class="pre">DIR</span></code></dt>
<dd>Set the script installation directory.  If you don’t supply this option
(via the command line or a configuration file), but you <em>have</em> supplied
an <code class="docutils literal notranslate"><span class="pre">--install-dir</span></code> (via command line or config file), then this option
defaults to the same directory, so that the scripts will be able to find
their associated package installation.  Otherwise, this setting defaults
to the location where the distutils would normally install scripts, taking
any distutils configuration file settings into account.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--exclude-scripts,</span> <span class="pre">-x</span></code></dt>
<dd>Don’t install scripts.  This is useful if you need to install multiple
versions of a package, but do not want to reset the version that will be
run by scripts that are already installed.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--user</span></code> (New in 0.6.11)</dt>
<dd>Use the user-site-packages as specified in <span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0370"><strong>PEP 370</strong></a>
instead of the global site-packages.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--always-copy,</span> <span class="pre">-a</span></code>   (New in 0.5a4)</dt>
<dd><p class="first">Copy all needed distributions to the installation directory, even if they
are already present in a directory on sys.path.  In older versions of
EasyInstall, this was the default behavior, but now you must explicitly
request it.  By default, EasyInstall will no longer copy such distributions
from other sys.path directories to the installation directory, unless you
explicitly gave the distribution’s filename on the command line.</p>
<p class="last">Note that as of 0.6a10, using this option excludes “system” and
“development” eggs from consideration because they can’t be reliably
copied.  This may cause EasyInstall to choose an older version of a package
than what you expected, or it may cause downloading and installation of a
fresh copy of something that’s already installed.  You will see warning
messages for any eggs that EasyInstall skips, before it falls back to an
older version or attempts to download a fresh copy.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--find-links=URLS_OR_FILENAMES,</span> <span class="pre">-f</span> <span class="pre">URLS_OR_FILENAMES</span></code></dt>
<dd><p class="first">Scan the specified “download pages” or directories for direct links to eggs
or other distributions.  Any existing file or directory names or direct
download URLs are immediately added to EasyInstall’s search cache, and any
indirect URLs (ones that don’t point to eggs or other recognized archive
formats) are added to a list of additional places to search for download
links.  As soon as EasyInstall has to go online to find a package (either
because it doesn’t exist locally, or because <code class="docutils literal notranslate"><span class="pre">--upgrade</span></code> or <code class="docutils literal notranslate"><span class="pre">-U</span></code> was
used), the specified URLs will be downloaded and scanned for additional
direct links.</p>
<p>Eggs and archives found by way of <code class="docutils literal notranslate"><span class="pre">--find-links</span></code> are only downloaded if
they are needed to meet a requirement specified on the command line; links
to unneeded packages are ignored.</p>
<p>If all requested packages can be found using links on the specified
download pages, the Python Package Index will not be consulted unless you
also specified the <code class="docutils literal notranslate"><span class="pre">--upgrade</span></code> or <code class="docutils literal notranslate"><span class="pre">-U</span></code> option.</p>
<p>(Note: if you want to refer to a local HTML file containing links, you must
use a <code class="docutils literal notranslate"><span class="pre">file:</span></code> URL, as filenames that do not refer to a directory, egg, or
archive are ignored.)</p>
<p>You may specify multiple URLs or file/directory names with this option,
separated by whitespace.  Note that on the command line, you will probably
have to surround the URL list with quotes, so that it is recognized as a
single option value.  You can also specify URLs in a configuration file;
see <a class="reference internal" href="#configuration-files">Configuration Files</a>, above.</p>
<p class="last">Changed in 0.6a10: previously all URLs and directories passed to this
option were scanned as early as possible, but from 0.6a10 on, only
directories and direct archive links are scanned immediately; URLs are not
retrieved unless a package search was already going to go online due to a
package not being available locally, or due to the use of the <code class="docutils literal notranslate"><span class="pre">--update</span></code>
or <code class="docutils literal notranslate"><span class="pre">-U</span></code> option.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--no-find-links</span></code> Blocks the addition of any link.</dt>
<dd><p class="first">This parameter is useful if you want to avoid adding links defined in a
project easy_install is installing (whether it’s a requested project or a
dependency). When used, <code class="docutils literal notranslate"><span class="pre">--find-links</span></code> is ignored.</p>
<p class="last">Added in Distribute 0.6.11 and Setuptools 0.7.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--index-url=URL,</span> <span class="pre">-i</span> <span class="pre">URL</span></code> (New in 0.4a1; default changed in 0.6c7)</dt>
<dd>Specifies the base URL of the Python Package Index.  The default is
<a class="reference external" href="https://pypi.org/simple/">https://pypi.org/simple/</a> if not specified.  When a package is requested
that is not locally available or linked from a <code class="docutils literal notranslate"><span class="pre">--find-links</span></code> download
page, the package index will be searched for download pages for the needed
package, and those download pages will be searched for links to download
an egg or source distribution.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--editable,</span> <span class="pre">-e</span></code> (New in 0.6a1)</dt>
<dd>Only find and download source distributions for the specified projects,
unpacking them to subdirectories of the specified <code class="docutils literal notranslate"><span class="pre">--build-directory</span></code>.
EasyInstall will not actually build or install the requested projects or
their dependencies; it will just find and extract them for you.  See
<a class="reference internal" href="#editing-and-viewing-source-packages">Editing and Viewing Source Packages</a> above for more details.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--build-directory=DIR,</span> <span class="pre">-b</span> <span class="pre">DIR</span></code> (UPDATED in 0.6a1)</dt>
<dd><p class="first">Set the directory used to build source packages.  If a package is built
from a source distribution or checkout, it will be extracted to a
subdirectory of the specified directory.  The subdirectory will have the
same name as the extracted distribution’s project, but in all-lowercase.
If a file or directory of that name already exists in the given directory,
a warning will be printed to the console, and the build will take place in
a temporary directory instead.</p>
<p class="last">This option is most useful in combination with the <code class="docutils literal notranslate"><span class="pre">--editable</span></code> option,
which forces EasyInstall to <em>only</em> find and extract (but not build and
install) source distributions.  See <a class="reference internal" href="#editing-and-viewing-source-packages">Editing and Viewing Source Packages</a>,
above, for more information.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--verbose,</span> <span class="pre">-v,</span> <span class="pre">--quiet,</span> <span class="pre">-q</span></code> (New in 0.4a4)</dt>
<dd>Control the level of detail of EasyInstall’s progress messages.  The
default detail level is “info”, which prints information only about
relatively time-consuming operations like running a setup script, unpacking
an archive, or retrieving a URL.  Using <code class="docutils literal notranslate"><span class="pre">-q</span></code> or <code class="docutils literal notranslate"><span class="pre">--quiet</span></code> drops the
detail level to “warn”, which will only display installation reports,
warnings, and errors.  Using <code class="docutils literal notranslate"><span class="pre">-v</span></code> or <code class="docutils literal notranslate"><span class="pre">--verbose</span></code> increases the detail
level to include individual file-level operations, link analysis messages,
and distutils messages from any setup scripts that get run.  If you include
the <code class="docutils literal notranslate"><span class="pre">-v</span></code> option more than once, the second and subsequent uses are passed
down to any setup scripts, increasing the verbosity of their reporting as
well.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--dry-run,</span> <span class="pre">-n</span></code> (New in 0.4a4)</dt>
<dd>Don’t actually install the package or scripts.  This option is passed down
to any setup scripts run, so packages should not actually build either.
This does <em>not</em> skip downloading, nor does it skip extracting source
distributions to a temporary/build directory.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--optimize=LEVEL</span></code>, <code class="docutils literal notranslate"><span class="pre">-O</span> <span class="pre">LEVEL</span></code> (New in 0.4a4)</dt>
<dd>If you are installing from a source distribution, and are <em>not</em> using the
<code class="docutils literal notranslate"><span class="pre">--zip-ok</span></code> option, this option controls the optimization level for
compiling installed <code class="docutils literal notranslate"><span class="pre">.py</span></code> files to <code class="docutils literal notranslate"><span class="pre">.pyo</span></code> files.  It does not affect
the compilation of modules contained in <code class="docutils literal notranslate"><span class="pre">.egg</span></code> files, only those in
<code class="docutils literal notranslate"><span class="pre">.egg</span></code> directories.  The optimization level can be set to 0, 1, or 2;
the default is 0 (unless it’s set under <code class="docutils literal notranslate"><span class="pre">install</span></code> or <code class="docutils literal notranslate"><span class="pre">install_lib</span></code> in
one of your distutils configuration files).</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--record=FILENAME</span></code>  (New in 0.5a4)</dt>
<dd>Write a record of all installed files to FILENAME.  This is basically the
same as the same option for the standard distutils “install” command, and
is included for compatibility with tools that expect to pass this option
to “setup.py install”.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--site-dirs=DIRLIST,</span> <span class="pre">-S</span> <span class="pre">DIRLIST</span></code>   (New in 0.6a1)</dt>
<dd>Specify one or more custom “site” directories (separated by commas).
“Site” directories are directories where <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files are processed, such
as the main Python <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory.  As of 0.6a10, EasyInstall
automatically detects whether a given directory processes <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files
(or can be made to do so), so you should not normally need to use this
option.  It is is now only necessary if you want to override EasyInstall’s
judgment and force an installation directory to be treated as if it
supported <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--no-deps,</span> <span class="pre">-N</span></code>  (New in 0.6a6)</dt>
<dd>Don’t install any dependencies.  This is intended as a convenience for
tools that wrap eggs in a platform-specific packaging system.  (We don’t
recommend that you use it for anything else.)</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--allow-hosts=PATTERNS,</span> <span class="pre">-H</span> <span class="pre">PATTERNS</span></code>   (New in 0.6a6)</dt>
<dd><p class="first">Restrict downloading and spidering to hosts matching the specified glob
patterns.  E.g. <code class="docutils literal notranslate"><span class="pre">-H</span> <span class="pre">*.python.org</span></code> restricts web access so that only
packages listed and downloadable from machines in the <code class="docutils literal notranslate"><span class="pre">python.org</span></code>
domain.  The glob patterns must match the <em>entire</em> user/host/port section of
the target URL(s).  For example, <code class="docutils literal notranslate"><span class="pre">*.python.org</span></code> will NOT accept a URL
like <code class="docutils literal notranslate"><span class="pre">http://python.org/foo</span></code> or <code class="docutils literal notranslate"><span class="pre">http://www.python.org:8080/</span></code>.
Multiple patterns can be specified by separating them with commas.  The
default pattern is <code class="docutils literal notranslate"><span class="pre">*</span></code>, which matches anything.</p>
<p class="last">In general, this option is mainly useful for blocking EasyInstall’s web
access altogether (e.g. <code class="docutils literal notranslate"><span class="pre">-Hlocalhost</span></code>), or to restrict it to an intranet
or other trusted site.  EasyInstall will do the best it can to satisfy
dependencies given your host restrictions, but of course can fail if it
can’t find suitable packages.  EasyInstall displays all blocked URLs, so
that you can adjust your <code class="docutils literal notranslate"><span class="pre">--allow-hosts</span></code> setting if it is more strict
than you intended.  Some sites may wish to define a restrictive default
setting for this option in their <a class="reference internal" href="#configuration-files">configuration files</a>, and then manually
override the setting on the command line as needed.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--prefix=DIR</span></code> (New in 0.6a10)</dt>
<dd><p class="first">Use the specified directory as a base for computing the default
installation and script directories.  On Windows, the resulting default
directories will be <code class="docutils literal notranslate"><span class="pre">prefix\\Lib\\site-packages</span></code> and <code class="docutils literal notranslate"><span class="pre">prefix\\Scripts</span></code>,
while on other platforms the defaults will be
<code class="docutils literal notranslate"><span class="pre">prefix/lib/python2.X/site-packages</span></code> (with the appropriate version
substituted) for libraries and <code class="docutils literal notranslate"><span class="pre">prefix/bin</span></code> for scripts.</p>
<p class="last">Note that the <code class="docutils literal notranslate"><span class="pre">--prefix</span></code> option only sets the <em>default</em> installation and
script directories, and does not override the ones set on the command line
or in a configuration file.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">--local-snapshots-ok,</span> <span class="pre">-l</span></code> (New in 0.6c6)</dt>
<dd><p class="first">Normally, EasyInstall prefers to only install <em>released</em> versions of
projects, not in-development ones, because such projects may not
have a currently-valid version number.  So, it usually only installs them
when their <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> directory is explicitly passed on the command line.</p>
<p>However, if this option is used, then any in-development projects that were
installed using the <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code> command, will be used to build
eggs, effectively upgrading the “in-development” project to a snapshot
release.  Normally, this option is used only in conjunction with the
<code class="docutils literal notranslate"><span class="pre">--always-copy</span></code> option to create a distributable snapshot of every egg
needed to run an application.</p>
<p class="last">Note that if you use this option, you must make sure that there is a valid
version number (such as an SVN revision number tag) for any in-development
projects that may be used, as otherwise EasyInstall may not be able to tell
what version of the project is “newer” when future installations or
upgrades are attempted.</p>
</dd>
</dl>
</div>
<div class="section" id="custom-installation-locations">
<span id="non-root-installation"></span><h4><a class="toc-backref" href="#id34">Custom Installation Locations</a><a class="headerlink" href="#custom-installation-locations" title="Permalink to this headline">¶</a></h4>
<p>By default, EasyInstall installs python packages into Python’s main <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> directory,
and manages them using a custom <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file in that same directory.</p>
<p>Very often though, a user or developer wants <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> to install and manage python packages
in an alternative location, usually for one of 3 reasons:</p>
<ol class="arabic simple">
<li>They don’t have access to write to the main Python site-packages directory.</li>
<li>They want a user-specific stash of packages, that is not visible to other users.</li>
<li>They want to isolate a set of packages to a specific python application, usually to minimize
the possibility of version conflicts.</li>
</ol>
<p>Historically, there have been many approaches to achieve custom installation.
The following section lists only the easiest and most relevant approaches <a class="footnote-reference" href="#id3" id="id2">[1]</a>.</p>
<p><a class="reference internal" href="#use-the-user-option">Use the “–user” option</a></p>
<p><a class="reference internal" href="#use-the-user-option-and-customize-pythonuserbase">Use the “–user” option and customize “PYTHONUSERBASE”</a></p>
<p><a class="reference internal" href="#use-virtualenv">Use “virtualenv”</a></p>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>There are older ways to achieve custom installation using various <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> and <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">install</span></code> options, combined with <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> and/or <code class="docutils literal notranslate"><span class="pre">PYTHONUSERBASE</span></code> alterations, but all of these are effectively deprecated by the User scheme brought in by <a class="reference external" href="http://www.python.org/dev/peps/pep-0370/">PEP-370</a>.</td></tr>
</tbody>
</table>
<div class="section" id="use-the-user-option">
<h5><a class="toc-backref" href="#id35">Use the “–user” option</a><a class="headerlink" href="#use-the-user-option" title="Permalink to this headline">¶</a></h5>
<p>Python provides a User scheme for installation, which means that all
python distributions support an alternative install location that is specific to a user <a class="footnote-reference" href="#id5" id="id4">[3]</a>.
The Default location for each OS is explained in the python documentation
for the <code class="docutils literal notranslate"><span class="pre">site.USER_BASE</span></code> variable.  This mode of installation can be turned on by
specifying the <code class="docutils literal notranslate"><span class="pre">--user</span></code> option to <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">install</span></code> or <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>.
This approach serves the need to have a user-specific stash of packages.</p>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[3]</a></td><td>Prior to the User scheme, there was the Home scheme, which is still available, but requires more effort than the User scheme to get packages recognized.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="use-the-user-option-and-customize-pythonuserbase">
<h5><a class="toc-backref" href="#id36">Use the “–user” option and customize “PYTHONUSERBASE”</a><a class="headerlink" href="#use-the-user-option-and-customize-pythonuserbase" title="Permalink to this headline">¶</a></h5>
<p>The User scheme install location can be customized by setting the <code class="docutils literal notranslate"><span class="pre">PYTHONUSERBASE</span></code> environment
variable, which updates the value of <code class="docutils literal notranslate"><span class="pre">site.USER_BASE</span></code>.  To isolate packages to a specific
application, simply set the OS environment of that application to a specific value of
<code class="docutils literal notranslate"><span class="pre">PYTHONUSERBASE</span></code>, that contains just those packages.</p>
</div>
<div class="section" id="use-virtualenv">
<h5><a class="toc-backref" href="#id37">Use “virtualenv”</a><a class="headerlink" href="#use-virtualenv" title="Permalink to this headline">¶</a></h5>
<p>“virtualenv” is a 3rd-party python package that effectively “clones” a python installation, thereby
creating an isolated location to install packages.  The evolution of “virtualenv” started before the existence
of the User installation scheme.  “virtualenv” provides a version of <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> that is
scoped to the cloned python install and is used in the normal way. “virtualenv” does offer various features
that the User installation scheme alone does not provide, e.g. the ability to hide the main python site-packages.</p>
<p>Please refer to the <a class="reference external" href="https://pypi.org/project/virtualenv/">virtualenv</a> documentation for more details.</p>
</div>
</div>
<div class="section" id="package-index-api">
<h4><a class="toc-backref" href="#id38">Package Index “API”</a><a class="headerlink" href="#package-index-api" title="Permalink to this headline">¶</a></h4>
<p>Custom package indexes (and PyPI) must follow the following rules for
EasyInstall to be able to look up and download packages:</p>
<ol class="arabic">
<li><p class="first">Except where stated otherwise, “pages” are HTML or XHTML, and “links”
refer to <code class="docutils literal notranslate"><span class="pre">href</span></code> attributes.</p>
</li>
<li><p class="first">Individual project version pages’ URLs must be of the form
<code class="docutils literal notranslate"><span class="pre">base/projectname/version</span></code>, where <code class="docutils literal notranslate"><span class="pre">base</span></code> is the package index’s base URL.</p>
</li>
<li><p class="first">Omitting the <code class="docutils literal notranslate"><span class="pre">/version</span></code> part of a project page’s URL (but keeping the
trailing <code class="docutils literal notranslate"><span class="pre">/</span></code>) should result in a page that is either:</p>
<ol class="loweralpha simple">
<li>The single active version of that project, as though the version had been
explicitly included, OR</li>
<li>A page with links to all of the active version pages for that project.</li>
</ol>
</li>
<li><p class="first">Individual project version pages should contain direct links to downloadable
distributions where possible.  It is explicitly permitted for a project’s
“long_description” to include URLs, and these should be formatted as HTML
links by the package index, as EasyInstall does no special processing to
identify what parts of a page are index-specific and which are part of the
project’s supplied description.</p>
</li>
<li><p class="first">Where available, MD5 information should be added to download URLs by
appending a fragment identifier of the form <code class="docutils literal notranslate"><span class="pre">#md5=...</span></code>, where <code class="docutils literal notranslate"><span class="pre">...</span></code> is
the 32-character hex MD5 digest.  EasyInstall will verify that the
downloaded file’s MD5 digest matches the given value.</p>
</li>
<li><p class="first">Individual project version pages should identify any “homepage” or
“download” URLs using <code class="docutils literal notranslate"><span class="pre">rel=&quot;homepage&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">rel=&quot;download&quot;</span></code> attributes
on the HTML elements linking to those URLs. Use of these attributes will
cause EasyInstall to always follow the provided links, unless it can be
determined by inspection that they are downloadable distributions. If the
links are not to downloadable distributions, they are retrieved, and if they
are HTML, they are scanned for download links. They are <em>not</em> scanned for
additional “homepage” or “download” links, as these are only processed for
pages that are part of a package index site.</p>
</li>
<li><p class="first">The root URL of the index, if retrieved with a trailing <code class="docutils literal notranslate"><span class="pre">/</span></code>, must result
in a page containing links to <em>all</em> projects’ active version pages.</p>
<p>(Note: This requirement is a workaround for the absence of case-insensitive
<code class="docutils literal notranslate"><span class="pre">safe_name()</span></code> matching of project names in URL paths. If project names are
matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar
mechanism), then it is not necessary to include this all-packages listing
page.)</p>
</li>
<li><p class="first">If a package index is accessed via a <code class="docutils literal notranslate"><span class="pre">file://</span></code> URL, then EasyInstall will
automatically use <code class="docutils literal notranslate"><span class="pre">index.html</span></code> files, if present, when trying to read a
directory with a trailing <code class="docutils literal notranslate"><span class="pre">/</span></code> on the URL.</p>
</li>
</ol>
</div>
</div>
</div>
<span id="document-history"></span><div class="section" id="history">
<span id="changes"></span><h2>History<a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h2>
<div class="section" id="v46-1-3">
<h3>v46.1.3<a class="headerlink" href="#v46-1-3" title="Permalink to this headline">¶</a></h3>
<p>25 Mar 2020</p>
<p>No significant changes.</p>
</div>
<div class="section" id="v46-1-2">
<h3>v46.1.2<a class="headerlink" href="#v46-1-2" title="Permalink to this headline">¶</a></h3>
<p>25 Mar 2020</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1458">#1458</a>: Added template for reporting Python 2 incompatibilities.</li>
</ul>
</div>
<div class="section" id="v46-1-1">
<h3>v46.1.1<a class="headerlink" href="#v46-1-1" title="Permalink to this headline">¶</a></h3>
<p>21 Mar 2020</p>
<p>No significant changes.</p>
</div>
<div class="section" id="v46-1-0">
<h3>v46.1.0<a class="headerlink" href="#v46-1-0" title="Permalink to this headline">¶</a></h3>
<p>21 Mar 2020</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/308">#308</a>: Allow version number normalization to be bypassed by wrapping in a ‘setuptools.sic()’ call.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1424">#1424</a>: Prevent keeping files mode for package_data build. It may break a build if user’s package data has read only flag.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1431">#1431</a>: In <code class="docutils literal notranslate"><span class="pre">easy_install.check_site_dir</span></code>, ensure the installation directory exists.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1563">#1563</a>: In <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> prefer <code class="docutils literal notranslate"><span class="pre">find_spec</span></code> (<a class="reference external" href="https://www.python.org/dev/peps/pep-0451/">PEP 451</a>) to <code class="docutils literal notranslate"><span class="pre">find_module</span></code>.</li>
</ul>
<p>Incorporate changes from v44.1.0:</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1704">#1704</a>: Set sys.argv[0] in setup script run by build_meta.__legacy__</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1959">#1959</a>: Fix for Python 4: replace unsafe six.PY3 with six.PY2</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1994">#1994</a>: Fixed a bug in the “setuptools.finalize_distribution_options” hook that lead to ignoring the order attribute of entry points managed by this hook.</li>
</ul>
</div>
<div class="section" id="v44-1-0">
<h3>v44.1.0<a class="headerlink" href="#v44-1-0" title="Permalink to this headline">¶</a></h3>
<p>21 Mar 2020</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1704">#1704</a>: Set sys.argv[0] in setup script run by build_meta.__legacy__</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1959">#1959</a>: Fix for Python 4: replace unsafe six.PY3 with six.PY2</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1994">#1994</a>: Fixed a bug in the “setuptools.finalize_distribution_options” hook that lead to ignoring the order attribute of entry points managed by this hook.</li>
</ul>
</div>
<div class="section" id="v46-0-0">
<h3>v46.0.0<a class="headerlink" href="#v46-0-0" title="Permalink to this headline">¶</a></h3>
<p>08 Mar 2020</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/65">#65</a>: Once again as in 3.0, removed the Features feature.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1890">#1890</a>: Fix vendored dependencies so importing <code class="docutils literal notranslate"><span class="pre">setuptools.extern.some_module</span></code> gives the same object as <code class="docutils literal notranslate"><span class="pre">setuptools._vendor.some_module</span></code>. This makes Metadata picklable again.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1899">#1899</a>: Test suite now fails on warnings.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/2011">#2011</a>: Fix broken link to distutils docs on package_data</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1991">#1991</a>: Include pkg_resources test data in sdist, so tests can be executed from it.</li>
</ul>
</div>
<div class="section" id="v45-3-0">
<h3>v45.3.0<a class="headerlink" href="#v45-3-0" title="Permalink to this headline">¶</a></h3>
<p>07 Mar 2020</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1557">#1557</a>: Deprecated eggsecutable scripts and updated docs.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1904">#1904</a>: Update msvc.py to use CPython 3.8.0 mechanism to find msvc 14+</li>
</ul>
</div>
<div class="section" id="v45-2-0">
<h3>v45.2.0<a class="headerlink" href="#v45-2-0" title="Permalink to this headline">¶</a></h3>
<p>08 Feb 2020</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1905">#1905</a>: Fixed defect in _imp, introduced in 41.6.0 when the ‘tests’ directory is not present.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1941">#1941</a>: Improve editable installs with <a class="reference external" href="https://www.python.org/dev/peps/pep-0518/">PEP 518</a> build isolation:<ul>
<li>The <code class="docutils literal notranslate"><span class="pre">--user</span></code> option is now always available. A warning is issued if the user site directory is not available.</li>
<li>The error shown when the install directory is not in <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> has been turned into a warning.</li>
</ul>
</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1981">#1981</a>: Setuptools now declares its <code class="docutils literal notranslate"><span class="pre">tests</span></code> and <code class="docutils literal notranslate"><span class="pre">docs</span></code> dependencies in metadata (extras).</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1985">#1985</a>: Add support for installing scripts in environments where bdist_wininst is missing (i.e. Python 3.9).</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1968">#1968</a>: Add flake8-2020 to check for misuse of sys.version or sys.version_info.</li>
</ul>
</div>
<div class="section" id="v45-1-0">
<h3>v45.1.0<a class="headerlink" href="#v45-1-0" title="Permalink to this headline">¶</a></h3>
<p>19 Jan 2020</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1458">#1458</a>: Add minimum sunset date and preamble to Python 2 warning.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1704">#1704</a>: Set sys.argv[0] in setup script run by build_meta.__legacy__</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1974">#1974</a>: Add Python 3 Only Trove Classifier and remove universal wheel declaration for more complete transition from Python 2.</li>
</ul>
</div>
<div class="section" id="v45-0-0">
<h3>v45.0.0<a class="headerlink" href="#v45-0-0" title="Permalink to this headline">¶</a></h3>
<p>11 Jan 2020</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1458">#1458</a>: Drop support for Python 2. Setuptools now requires Python 3.5 or later. Install setuptools using pip &gt;=9 or pin to Setuptools &lt;45 to maintain 2.7 support.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1959">#1959</a>: Fix for Python 4: replace unsafe six.PY3 with six.PY2</li>
</ul>
</div>
<div class="section" id="v44-0-0">
<h3>v44.0.0<a class="headerlink" href="#v44-0-0" title="Permalink to this headline">¶</a></h3>
<p>01 Jan 2020</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1908">#1908</a>: Drop support for Python 3.4.</li>
</ul>
</div>
<div class="section" id="v43-0-0">
<h3>v43.0.0<a class="headerlink" href="#v43-0-0" title="Permalink to this headline">¶</a></h3>
<p>31 Dec 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1634">#1634</a>: Include <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> in source distribution by default. Projects relying on the previous behavior where <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> was excluded by default should stop relying on that behavior or add <code class="docutils literal notranslate"><span class="pre">exclude</span> <span class="pre">pyproject.toml</span></code> to their MANIFEST.in file.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1927">#1927</a>: Setuptools once again declares ‘setuptools’ in the <code class="docutils literal notranslate"><span class="pre">build-system.requires</span></code> and adds <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a> build support by declaring itself as the <code class="docutils literal notranslate"><span class="pre">build-backend</span></code>. It additionally specifies <code class="docutils literal notranslate"><span class="pre">build-system.backend-path</span></code> to rely on itself for those builders that support it.</li>
</ul>
</div>
<div class="section" id="v42-0-2">
<h3>v42.0.2<a class="headerlink" href="#v42-0-2" title="Permalink to this headline">¶</a></h3>
<p>01 Dec 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1921">#1921</a>: Fix support for easy_install’s <code class="docutils literal notranslate"><span class="pre">find-links</span></code> option in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1922">#1922</a>: Build dependencies (setup_requires and tests_require) now install transitive dependencies indicated by extras.</li>
</ul>
</div>
<div class="section" id="v42-0-1">
<h3>v42.0.1<a class="headerlink" href="#v42-0-1" title="Permalink to this headline">¶</a></h3>
<p>25 Nov 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1918">#1918</a>: Fix regression in handling wheels compatibility tags.</li>
</ul>
</div>
<div class="section" id="v42-0-0">
<h3>v42.0.0<a class="headerlink" href="#v42-0-0" title="Permalink to this headline">¶</a></h3>
<p>23 Nov 2019</p>
<ul class="simple">
<li><dl class="first docutils">
<dt><a class="reference external" href="https://github.com/pypa/setuptools/issues/1830">#1830</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/1909">#1909</a>: Mark the easy_install script and setuptools command as deprecated, and use <a class="reference external" href="https://pip.pypa.io/en/stable/">pip</a> when available to fetch/build wheels for missing <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code>/<code class="docutils literal notranslate"><span class="pre">tests_require</span></code> requirements, with the following differences in behavior:</dt>
<dd><ul class="first last">
<li>support for <code class="docutils literal notranslate"><span class="pre">python_requires</span></code></li>
<li>better support for wheels (proper handling of priority with respect to <a class="reference external" href="https://www.python.org/dev/peps/pep-0425/">PEP 425</a> tags)</li>
<li><a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a>/518 support</li>
<li>eggs are not supported</li>
<li>no support for the <code class="docutils literal notranslate"><span class="pre">allow_hosts</span></code> easy_install option (<code class="docutils literal notranslate"><span class="pre">index_url</span></code>/<code class="docutils literal notranslate"><span class="pre">find_links</span></code> are still honored)</li>
<li>pip environment variables are honored (and take precedence over easy_install options)</li>
</ul>
</dd>
</dl>
</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1898">#1898</a>: Removed the “upload” and “register” commands in favor of <a class="reference external" href="https://pypi.org/p/twine">twine</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1767">#1767</a>: Add support for the <code class="docutils literal notranslate"><span class="pre">license_files</span></code> option in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> to automatically
include multiple license files in a source distribution.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1829">#1829</a>: Update handling of wheels compatibility tags:
* add support for manylinux2010
* fix use of removed ‘m’ ABI flag in Python 3.8 on Windows</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1861">#1861</a>: Fix empty namespace package installation from wheel.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1877">#1877</a>: Setuptools now exposes a new entry point hook “setuptools.finalize_distribution_options”, enabling plugins like <a class="reference external" href="https://pypi.org/project/setuptools_scm">setuptools_scm</a> to configure options on the distribution at finalization time.</li>
</ul>
</div>
<div class="section" id="v41-6-0">
<h3>v41.6.0<a class="headerlink" href="#v41-6-0" title="Permalink to this headline">¶</a></h3>
<p>29 Oct 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/479">#479</a>: Replace usage of deprecated <code class="docutils literal notranslate"><span class="pre">imp</span></code> module with local re-implementation in <code class="docutils literal notranslate"><span class="pre">setuptools._imp</span></code>.</li>
</ul>
</div>
<div class="section" id="v41-5-1">
<h3>v41.5.1<a class="headerlink" href="#v41-5-1" title="Permalink to this headline">¶</a></h3>
<p>28 Oct 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1891">#1891</a>: Fix code for detecting Visual Studio’s version on Windows under Python 2.</li>
</ul>
</div>
<div class="section" id="v41-5-0">
<h3>v41.5.0<a class="headerlink" href="#v41-5-0" title="Permalink to this headline">¶</a></h3>
<p>27 Oct 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1811">#1811</a>: Improve Visual C++ 14.X support, mainly for Visual Studio 2017 and 2019.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1814">#1814</a>: Fix <code class="docutils literal notranslate"><span class="pre">pkg_resources.Requirement</span></code> hash/equality implementation: take <a class="reference external" href="https://www.python.org/dev/peps/pep-0508/">PEP 508</a> direct URL into account.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1824">#1824</a>: Fix tests when running under <code class="docutils literal notranslate"><span class="pre">python3.10</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1878">#1878</a>: Formally deprecated the <code class="docutils literal notranslate"><span class="pre">test</span></code> command, with the recommendation that users migrate to <code class="docutils literal notranslate"><span class="pre">tox</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1860">#1860</a>: Update documentation to mention the egg format is not supported by pip and dependency links support was dropped starting with pip 19.0.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1862">#1862</a>: Drop ez_setup documentation: deprecated for some time (last updated in 2016), and still relying on easy_install (deprecated too).</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1868">#1868</a>: Drop most documentation references to (deprecated) EasyInstall.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1884">#1884</a>: Added a trove classifier to document support for Python 3.8.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1886">#1886</a>: Added Python 3.8 release to the Travis test matrix.</li>
</ul>
</div>
<div class="section" id="v41-4-0">
<h3>v41.4.0<a class="headerlink" href="#v41-4-0" title="Permalink to this headline">¶</a></h3>
<p>06 Oct 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1847">#1847</a>: In declarative config, now traps errors when invalid <code class="docutils literal notranslate"><span class="pre">python_requires</span></code> values are supplied.</li>
</ul>
</div>
<div class="section" id="v41-3-0">
<h3>v41.3.0<a class="headerlink" href="#v41-3-0" title="Permalink to this headline">¶</a></h3>
<p>06 Oct 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1690">#1690</a>: When storing extras, rely on OrderedSet to retain order of extras as indicated by the packager, which will also be deterministic on Python 2.7 (with PYTHONHASHSEED unset) and Python 3.6+.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1858">#1858</a>: Fixed failing integration test triggered by ‘long_description_content_type’ in packaging.</li>
</ul>
</div>
<div class="section" id="v41-2-0">
<h3>v41.2.0<a class="headerlink" href="#v41-2-0" title="Permalink to this headline">¶</a></h3>
<p>21 Aug 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/479">#479</a>: Remove some usage of the deprecated <code class="docutils literal notranslate"><span class="pre">imp</span></code> module.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1565">#1565</a>: Changed html_sidebars from string to list of string as per
<a class="reference external" href="https://www.sphinx-doc.org/en/master/changes.html#id58">https://www.sphinx-doc.org/en/master/changes.html#id58</a></li>
</ul>
</div>
<div class="section" id="v41-1-0">
<h3>v41.1.0<a class="headerlink" href="#v41-1-0" title="Permalink to this headline">¶</a></h3>
<p>13 Aug 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1697">#1697</a>: Moved most of the constants from setup.py to setup.cfg</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1749">#1749</a>: Fixed issue with the <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a> backend where building a source distribution would fail if any tarball existed in the destination directory.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1750">#1750</a>: Fixed an issue with <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a> backend where wheel builds would fail if the destination directory did not already exist.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1756">#1756</a>: Force metadata-version &gt;= 1.2. when project urls are present.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1769">#1769</a>: Improve <code class="docutils literal notranslate"><span class="pre">package_data</span></code> check: ensure the dictionary values are lists/tuples of strings.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1788">#1788</a>: Changed compatibility fallback logic for <code class="docutils literal notranslate"><span class="pre">html.unescape</span></code> to avoid accessing <code class="docutils literal notranslate"><span class="pre">HTMLParser.unescape</span></code> when not necessary. <code class="docutils literal notranslate"><span class="pre">HTMLParser.unescape</span></code> is deprecated and will be removed in Python 3.9.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1790">#1790</a>: Added the file path to the error message when a <code class="docutils literal notranslate"><span class="pre">UnicodeDecodeError</span></code> occurs while reading a metadata file.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1776">#1776</a>: Use license classifiers rather than the license field.</li>
</ul>
</div>
<div class="section" id="v41-0-1">
<h3>v41.0.1<a class="headerlink" href="#v41-0-1" title="Permalink to this headline">¶</a></h3>
<p>22 Apr 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1671">#1671</a>: Fixed issue with the <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a> backend that prevented building a wheel when the <code class="docutils literal notranslate"><span class="pre">dist/</span></code> directory contained existing <code class="docutils literal notranslate"><span class="pre">.whl</span></code> files.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1709">#1709</a>: In test.paths_on_python_path, avoid adding unnecessary duplicates to the PYTHONPATH.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1741">#1741</a>: In package_index, now honor “current directory” during a checkout of git and hg repositories under Windows</li>
</ul>
</div>
<div class="section" id="v41-0-0">
<h3>v41.0.0<a class="headerlink" href="#v41-0-0" title="Permalink to this headline">¶</a></h3>
<p>05 Apr 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1735">#1735</a>: When parsing setup.cfg files, setuptools now requires the files to be encoded as UTF-8. Any other encoding will lead to a UnicodeDecodeError. This change removes support for specifying an encoding using a ‘coding: ‘ directive in the header of the file, a feature that was introduces in 40.7. Given the recent release of the aforementioned feature, it is assumed that few if any projects are utilizing the feature to specify an encoding other than UTF-8.</li>
</ul>
</div>
<div class="section" id="v40-9-0">
<h3>v40.9.0<a class="headerlink" href="#v40-9-0" title="Permalink to this headline">¶</a></h3>
<p>03 Apr 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1675">#1675</a>: Added support for <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>-only projects when using the <code class="docutils literal notranslate"><span class="pre">setuptools.build_meta</span></code> backend. Projects that have enabled <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a> no longer need to have a <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> and can use the purely declarative <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> configuration file instead.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1720">#1720</a>: Added support for <code class="docutils literal notranslate"><span class="pre">pkg_resources.parse_requirements</span></code>-style requirements in <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> when <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> is invoked from the <code class="docutils literal notranslate"><span class="pre">setuptools.build_meta</span></code> build backend.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1664">#1664</a>: Added the path to the <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> or <code class="docutils literal notranslate"><span class="pre">METADATA</span></code> file in the exception
text when the <code class="docutils literal notranslate"><span class="pre">Version:</span></code> header can’t be found.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1705">#1705</a>: Removed some placeholder documentation sections referring to deprecated features.</li>
</ul>
</div>
<div class="section" id="v40-8-0">
<h3>v40.8.0<a class="headerlink" href="#v40-8-0" title="Permalink to this headline">¶</a></h3>
<p>05 Feb 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1652">#1652</a>: Added the <code class="docutils literal notranslate"><span class="pre">build_meta:__legacy__</span></code> backend, a “compatibility mode” <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a> backend that can be used as the default when <code class="docutils literal notranslate"><span class="pre">build-backend</span></code> is left unspecified in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1635">#1635</a>: Resource paths are passed to <code class="docutils literal notranslate"><span class="pre">pkg_resources.resource_string</span></code> and similar no longer accept paths that traverse parents, that begin with a leading <code class="docutils literal notranslate"><span class="pre">/</span></code>. Violations of this expectation raise DeprecationWarnings and will become errors. Additionally, any paths that are absolute on Windows are strictly disallowed and will raise ValueErrors.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1536">#1536</a>: <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> will now automatically include licenses if <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> contains a <code class="docutils literal notranslate"><span class="pre">license_file</span></code> attribute, unless this file is manually excluded inside <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code>.</li>
</ul>
</div>
<div class="section" id="v40-7-3">
<h3>v40.7.3<a class="headerlink" href="#v40-7-3" title="Permalink to this headline">¶</a></h3>
<p>03 Feb 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1670">#1670</a>: In package_index, revert to using a copy of splituser from Python 3.8. Attempts to use <code class="docutils literal notranslate"><span class="pre">urllib.parse.urlparse</span></code> led to problems as reported in <a class="reference external" href="https://github.com/pypa/setuptools/issues/1663">#1663</a> and <a class="reference external" href="https://github.com/pypa/setuptools/issues/1668">#1668</a>. This change serves as an alternative to <a class="reference external" href="https://github.com/pypa/setuptools/issues/1499">#1499</a> and fixes <a class="reference external" href="https://github.com/pypa/setuptools/issues/1668">#1668</a>.</li>
</ul>
</div>
<div class="section" id="v40-7-2">
<h3>v40.7.2<a class="headerlink" href="#v40-7-2" title="Permalink to this headline">¶</a></h3>
<p>31 Jan 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1666">#1666</a>: Restore port in URL handling in package_index.</li>
</ul>
</div>
<div class="section" id="v40-7-1">
<h3>v40.7.1<a class="headerlink" href="#v40-7-1" title="Permalink to this headline">¶</a></h3>
<p>28 Jan 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1660">#1660</a>: On Python 2, when reading config files, downcast options from text to bytes to satisfy distutils expectations.</li>
</ul>
</div>
<div class="section" id="v40-7-0">
<h3>v40.7.0<a class="headerlink" href="#v40-7-0" title="Permalink to this headline">¶</a></h3>
<p>27 Jan 2019</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1551">#1551</a>: File inputs for the <cite>license</cite> field in <cite>setup.cfg</cite> files now explicitly raise an error.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1180">#1180</a>: Add support for non-ASCII in setup.cfg (<a class="reference external" href="https://github.com/pypa/setuptools/issues/1062">#1062</a>). Add support for native strings on some parameters (<a class="reference external" href="https://github.com/pypa/setuptools/issues/1136">#1136</a>).</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1499">#1499</a>: <code class="docutils literal notranslate"><span class="pre">setuptools.package_index</span></code> no longer relies on the deprecated <code class="docutils literal notranslate"><span class="pre">urllib.parse.splituser</span></code> per <a class="reference external" href="http://bugs.python.org/issue27485">Python #27485</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1544">#1544</a>: Added tests for PackageIndex.download (for git URLs).</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1625">#1625</a>: In <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a> build_meta builder, ensure that sdists are built as gztar per the spec.</li>
</ul>
</div>
<div class="section" id="v40-6-3">
<h3>v40.6.3<a class="headerlink" href="#v40-6-3" title="Permalink to this headline">¶</a></h3>
<p>11 Dec 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1594">#1594</a>: <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a> backend no longer declares setuptools as a dependency as it can be assumed.</li>
</ul>
</div>
<div class="section" id="v40-6-2">
<h3>v40.6.2<a class="headerlink" href="#v40-6-2" title="Permalink to this headline">¶</a></h3>
<p>13 Nov 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1592">#1592</a>: Fix invalid dependency on external six module (instead of vendored version).</li>
</ul>
</div>
<div class="section" id="v40-6-1">
<h3>v40.6.1<a class="headerlink" href="#v40-6-1" title="Permalink to this headline">¶</a></h3>
<p>12 Nov 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1590">#1590</a>: Fixed regression where packages without <code class="docutils literal notranslate"><span class="pre">author</span></code> or <code class="docutils literal notranslate"><span class="pre">author_email</span></code> fields generated malformed package metadata.</li>
</ul>
</div>
<div class="section" id="v40-6-0">
<h3>v40.6.0<a class="headerlink" href="#v40-6-0" title="Permalink to this headline">¶</a></h3>
<p>12 Nov 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1541">#1541</a>: Officially deprecated the <code class="docutils literal notranslate"><span class="pre">requires</span></code> parameter in <code class="docutils literal notranslate"><span class="pre">setup()</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1519">#1519</a>: In <code class="docutils literal notranslate"><span class="pre">pkg_resources.normalize_path</span></code>, additional path normalization is now performed to ensure path values to a directory is always the same, preventing false positives when checking scripts have a consistent prefix to set up on Windows.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1545">#1545</a>: Changed the warning class of all deprecation warnings; deprecation warning classes are no longer derived from <code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code> and are thus visible by default.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1554">#1554</a>: <code class="docutils literal notranslate"><span class="pre">build_meta.build_sdist</span></code> now includes <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> in source distributions by default.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1576">#1576</a>: Started monkey-patching <code class="docutils literal notranslate"><span class="pre">get_metadata_version</span></code> and <code class="docutils literal notranslate"><span class="pre">read_pkg_file</span></code> onto <code class="docutils literal notranslate"><span class="pre">distutils.DistributionMetadata</span></code> to retain the correct version on the <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> file in the (deprecated) <code class="docutils literal notranslate"><span class="pre">upload</span></code> command.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1533">#1533</a>: Restricted the <code class="docutils literal notranslate"><span class="pre">recursive-include</span> <span class="pre">setuptools/_vendor</span></code> to contain only .py and .txt files.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1395">#1395</a>: Changed Pyrex references to Cython in the documentation.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1456">#1456</a>: Documented that the <code class="docutils literal notranslate"><span class="pre">rpmbuild</span></code> packages is required for the <code class="docutils literal notranslate"><span class="pre">bdist_rpm</span></code> command.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1537">#1537</a>: Documented how to use <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> for <code class="docutils literal notranslate"><span class="pre">src/</span> <span class="pre">layouts</span></code></li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1539">#1539</a>: Added minimum version column in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> metadata table.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1552">#1552</a>: Fixed a minor typo in the python 2/3 compatibility documentation.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1553">#1553</a>: Updated installation instructions to point to <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span></code> instead of <code class="docutils literal notranslate"><span class="pre">ez_setup.py</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1560">#1560</a>: Updated <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> distribution documentation to remove some outdated information.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1564">#1564</a>: Documented <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> minimum version for version and project_urls.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1572">#1572</a>: Added the <code class="docutils literal notranslate"><span class="pre">concurrent.futures</span></code> backport <code class="docutils literal notranslate"><span class="pre">futures</span></code> to the Python 2.7 test suite requirements.</li>
</ul>
</div>
<div class="section" id="v40-5-0">
<h3>v40.5.0<a class="headerlink" href="#v40-5-0" title="Permalink to this headline">¶</a></h3>
<p>26 Oct 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1335">#1335</a>: In <code class="docutils literal notranslate"><span class="pre">pkg_resources.normalize_path</span></code>, fix issue on Cygwin when cwd contains symlinks.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1502">#1502</a>: Deprecated support for downloads from Subversion in package_index/easy_install.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1517">#1517</a>: Dropped use of six.u in favor of <cite>u”“</cite> literals.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1520">#1520</a>: Added support for <code class="docutils literal notranslate"><span class="pre">data_files</span></code> in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1525">#1525</a>: Fixed rendering of the deprecation warning in easy_install doc.</li>
</ul>
</div>
<div class="section" id="v40-4-3">
<h3>v40.4.3<a class="headerlink" href="#v40-4-3" title="Permalink to this headline">¶</a></h3>
<p>23 Sep 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1480">#1480</a>: Bump vendored pyparsing in pkg_resources to 2.2.1.</li>
</ul>
</div>
<div class="section" id="v40-4-2">
<h3>v40.4.2<a class="headerlink" href="#v40-4-2" title="Permalink to this headline">¶</a></h3>
<p>21 Sep 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1497">#1497</a>: Updated gitignore in repo.</li>
</ul>
</div>
<div class="section" id="v40-4-1">
<h3>v40.4.1<a class="headerlink" href="#v40-4-1" title="Permalink to this headline">¶</a></h3>
<p>18 Sep 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1480">#1480</a>: Bump vendored pyparsing to 2.2.1.</li>
</ul>
</div>
<div class="section" id="v40-4-0">
<h3>v40.4.0<a class="headerlink" href="#v40-4-0" title="Permalink to this headline">¶</a></h3>
<p>18 Sep 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1481">#1481</a>: Join the sdist <code class="docutils literal notranslate"><span class="pre">--dist-dir</span></code> and the <code class="docutils literal notranslate"><span class="pre">build_meta</span></code> sdist directory argument to point to the same target (meaning the build frontend no longer needs to clean manually the dist dir to avoid multiple sdist presence, and setuptools no longer needs to handle conflicts between the two).</li>
</ul>
</div>
<div class="section" id="v40-3-0">
<h3>v40.3.0<a class="headerlink" href="#v40-3-0" title="Permalink to this headline">¶</a></h3>
<p>16 Sep 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1402">#1402</a>: Fixed a bug with namespace packages under Python 3.6 when one package in
current directory hides another which is installed.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1427">#1427</a>: Set timestamp of <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> directory whenever <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command is run.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1474">#1474</a>: <code class="docutils literal notranslate"><span class="pre">build_meta.get_requires_for_build_sdist</span></code> now does not include the <code class="docutils literal notranslate"><span class="pre">wheel</span></code> package anymore.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1486">#1486</a>: Suppress warnings in pkg_resources.handle_ns.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1479">#1479</a>: Remove internal use of six.binary_type.</li>
</ul>
</div>
<div class="section" id="v40-2-0">
<h3>v40.2.0<a class="headerlink" href="#v40-2-0" title="Permalink to this headline">¶</a></h3>
<p>21 Aug 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1466">#1466</a>: Fix handling of Unicode arguments in <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a> backend</li>
</ul>
</div>
<div class="section" id="v40-1-1">
<h3>v40.1.1<a class="headerlink" href="#v40-1-1" title="Permalink to this headline">¶</a></h3>
<p>21 Aug 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1465">#1465</a>: Fix regression with <cite>egg_info</cite> command when tagging is used.</li>
</ul>
</div>
<div class="section" id="v40-1-0">
<h3>v40.1.0<a class="headerlink" href="#v40-1-0" title="Permalink to this headline">¶</a></h3>
<p>17 Aug 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1410">#1410</a>: Deprecated <code class="docutils literal notranslate"><span class="pre">upload</span></code> and <code class="docutils literal notranslate"><span class="pre">register</span></code> commands.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1312">#1312</a>: Introduced find_namespace_packages() to find <a class="reference external" href="https://www.python.org/dev/peps/pep-0420/">PEP 420</a> namespace packages.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1420">#1420</a>: Added find_namespace: directive to config parser.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1418">#1418</a>: Solved race in when creating egg cache directories.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1450">#1450</a>: Upgraded vendored PyParsing from 2.1.10 to 2.2.0.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1451">#1451</a>: Upgraded vendored appdirs from 1.4.0 to 1.4.3.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1388">#1388</a>: Fixed “Microsoft Visual C++ Build Tools” link in exception when Visual C++ not found.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1389">#1389</a>: Added support for scripts which have unicode content.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1416">#1416</a>: Moved several Python version checks over to using <code class="docutils literal notranslate"><span class="pre">six.PY2</span></code> and <code class="docutils literal notranslate"><span class="pre">six.PY3</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1441">#1441</a>: Removed spurious executable permissions from files that don’t need them.</li>
</ul>
</div>
<div class="section" id="v40-0-0">
<h3>v40.0.0<a class="headerlink" href="#v40-0-0" title="Permalink to this headline">¶</a></h3>
<p>09 Jul 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1342">#1342</a>: Drop support for Python 3.3.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1366">#1366</a>: In package_index, fixed handling of encoded entities in URLs.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1383">#1383</a>: In pkg_resources VendorImporter, avoid removing packages imported from the root.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1379">#1379</a>: Minor doc fixes after actually using the new release process.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1385">#1385</a>: Removed section on non-package data files.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1403">#1403</a>: Fix developer’s guide.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1404">#1404</a>: Fix <a class="reference external" href="https://www.python.org/dev/peps/pep-0518/">PEP 518</a> configuration: set build requirements in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> to <code class="docutils literal notranslate"><span class="pre">[&quot;wheel&quot;]</span></code>.</li>
</ul>
</div>
<div class="section" id="v39-2-0">
<h3>v39.2.0<a class="headerlink" href="#v39-2-0" title="Permalink to this headline">¶</a></h3>
<p>19 May 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1359">#1359</a>: Support using “file:” to load a <a class="reference external" href="https://www.python.org/dev/peps/pep-0440/">PEP 440</a>-compliant package version from
a text file.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1360">#1360</a>: Fixed issue with a mismatch between the name of the package and the
name of the .dist-info file in wheel files</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1364">#1364</a>: Add <cite>__dir__()</cite> implementation to <cite>pkg_resources.Distribution()</cite> that
includes the attributes in the <cite>_provider</cite> instance variable.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1365">#1365</a>: Take the package_dir option into account when loading the version from
a module attribute.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1353">#1353</a>: Added coverage badge to README.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1356">#1356</a>: Made small fixes to the developer guide documentation.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1357">#1357</a>: Fixed warnings in documentation builds and started enforcing that the
docs build without warnings in tox.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1376">#1376</a>: Updated release process docs.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1343">#1343</a>: The <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> specific <code class="docutils literal notranslate"><span class="pre">long_description_content_type</span></code>,
<code class="docutils literal notranslate"><span class="pre">project_urls</span></code> and <code class="docutils literal notranslate"><span class="pre">provides_extras</span></code> fields are now set consistently
after any <code class="docutils literal notranslate"><span class="pre">distutils</span></code> <code class="docutils literal notranslate"><span class="pre">setup_keywords</span></code> calls, allowing them to override
values.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1352">#1352</a>: Added <code class="docutils literal notranslate"><span class="pre">tox</span></code> environment for documentation builds.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1354">#1354</a>: Added <code class="docutils literal notranslate"><span class="pre">towncrier</span></code> for changelog management.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1355">#1355</a>: Add PR template.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1368">#1368</a>: Fixed tests which failed without network connectivity.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1369">#1369</a>: Added unit tests for <a class="reference external" href="https://www.python.org/dev/peps/pep-0425/">PEP 425</a> compatibility tags support.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1372">#1372</a>: Stop testing Python 3.3 in Travis CI, now that the latest version of
<code class="docutils literal notranslate"><span class="pre">wheel</span></code> no longer installs on it.</li>
</ul>
</div>
<div class="section" id="v39-1-0">
<h3>v39.1.0<a class="headerlink" href="#v39-1-0" title="Permalink to this headline">¶</a></h3>
<p>28 Apr 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1340">#1340</a>: Update all PyPI URLs to reflect the switch to the
new Warehouse codebase.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1337">#1337</a>: In <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>, now support loading resources
for modules loaded by the <code class="docutils literal notranslate"><span class="pre">SourcelessFileLoader</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1332">#1332</a>: Silence spurious wheel related warnings on Windows.</li>
</ul>
</div>
<div class="section" id="v39-0-1">
<h3>v39.0.1<a class="headerlink" href="#v39-0-1" title="Permalink to this headline">¶</a></h3>
<p>18 Mar 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1297">#1297</a>: Restore Unicode handling for Maintainer fields in
metadata.</li>
</ul>
</div>
<div class="section" id="v39-0-0">
<h3>v39.0.0<a class="headerlink" href="#v39-0-0" title="Permalink to this headline">¶</a></h3>
<p>17 Mar 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1296">#1296</a>: Setuptools now vendors its own direct dependencies, no
longer relying on the dependencies as vendored by pkg_resources.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/296">#296</a>: Removed long-deprecated support for iteration on
Version objects as returned by <code class="docutils literal notranslate"><span class="pre">pkg_resources.parse_version</span></code>.
Removed the <code class="docutils literal notranslate"><span class="pre">SetuptoolsVersion</span></code> and
<code class="docutils literal notranslate"><span class="pre">SetuptoolsLegacyVersion</span></code> names as well. They should not
have been used, but if they were, replace with
<code class="docutils literal notranslate"><span class="pre">Version</span></code> and <code class="docutils literal notranslate"><span class="pre">LegacyVersion</span></code> from <code class="docutils literal notranslate"><span class="pre">packaging.version</span></code>.</li>
</ul>
</div>
<div class="section" id="v38-7-0">
<h3>v38.7.0<a class="headerlink" href="#v38-7-0" title="Permalink to this headline">¶</a></h3>
<p>17 Mar 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1288">#1288</a>: Add support for maintainer in PKG-INFO.</li>
</ul>
</div>
<div class="section" id="v38-6-1">
<h3>v38.6.1<a class="headerlink" href="#v38-6-1" title="Permalink to this headline">¶</a></h3>
<p>17 Mar 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1292">#1292</a>: Avoid generating <code class="docutils literal notranslate"><span class="pre">Provides-Extra</span></code> in metadata when
no extra is present (but environment markers are).</li>
</ul>
</div>
<div class="section" id="v38-6-0">
<h3>v38.6.0<a class="headerlink" href="#v38-6-0" title="Permalink to this headline">¶</a></h3>
<p>15 Mar 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1286">#1286</a>: Add support for Metadata 2.1 (<a class="reference external" href="https://www.python.org/dev/peps/pep-0566/">PEP 566</a>).</li>
</ul>
</div>
<div class="section" id="v38-5-2">
<h3>v38.5.2<a class="headerlink" href="#v38-5-2" title="Permalink to this headline">¶</a></h3>
<p>06 Mar 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1285">#1285</a>: Fixed RuntimeError in pkg_resources.parse_requirements
on Python 3.7 (stemming from <a class="reference external" href="https://www.python.org/dev/peps/pep-0479/">PEP 479</a>).</li>
</ul>
</div>
<div class="section" id="v38-5-1">
<h3>v38.5.1<a class="headerlink" href="#v38-5-1" title="Permalink to this headline">¶</a></h3>
<p>06 Feb 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1271">#1271</a>: Revert to Cython legacy <code class="docutils literal notranslate"><span class="pre">build_ext</span></code> behavior for
compatibility.</li>
</ul>
</div>
<div class="section" id="v38-5-0">
<h3>v38.5.0<a class="headerlink" href="#v38-5-0" title="Permalink to this headline">¶</a></h3>
<p>04 Feb 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1229">#1229</a>: Expand imports in <code class="docutils literal notranslate"><span class="pre">build_ext</span></code> to refine detection of
Cython availability.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1270">#1270</a>: When Cython is available, <code class="docutils literal notranslate"><span class="pre">build_ext</span></code> now uses the
new_build_ext.</li>
</ul>
</div>
<div class="section" id="v38-4-1">
<h3>v38.4.1<a class="headerlink" href="#v38-4-1" title="Permalink to this headline">¶</a></h3>
<p>03 Feb 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1257">#1257</a>: In bdist_egg.scan_module, fix ValueError on Python 3.7.</li>
</ul>
</div>
<div class="section" id="v38-4-0">
<h3>v38.4.0<a class="headerlink" href="#v38-4-0" title="Permalink to this headline">¶</a></h3>
<p>05 Jan 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1231">#1231</a>: Removed warning when PYTHONDONTWRITEBYTECODE is enabled.</li>
</ul>
</div>
<div class="section" id="v38-3-0">
<h3>v38.3.0<a class="headerlink" href="#v38-3-0" title="Permalink to this headline">¶</a></h3>
<p>04 Jan 2018</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1210">#1210</a>: Add support for <a class="reference external" href="https://www.python.org/dev/peps/pep-0345/">PEP 345</a> Project-URL metadata.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1207">#1207</a>: Add support for <code class="docutils literal notranslate"><span class="pre">long_description_type</span></code> to setup.cfg
declarative config as intended and documented.</li>
</ul>
</div>
<div class="section" id="v38-2-5">
<h3>v38.2.5<a class="headerlink" href="#v38-2-5" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1232">#1232</a>: Fix trailing slash handling in <code class="docutils literal notranslate"><span class="pre">pkg_resources.ZipProvider</span></code>.</li>
</ul>
</div>
<div class="section" id="v38-2-4">
<h3>v38.2.4<a class="headerlink" href="#v38-2-4" title="Permalink to this headline">¶</a></h3>
<p>04 Dec 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1220">#1220</a>: Fix <cite>data_files</cite> handling when installing from wheel.</li>
</ul>
</div>
<div class="section" id="v38-2-3">
<h3>v38.2.3<a class="headerlink" href="#v38-2-3" title="Permalink to this headline">¶</a></h3>
<p>28 Nov 2017</p>
<ul class="simple">
<li>fix Travis’ Python 3.3 job.</li>
</ul>
</div>
<div class="section" id="v38-2-2">
<h3>v38.2.2<a class="headerlink" href="#v38-2-2" title="Permalink to this headline">¶</a></h3>
<p>27 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1214">#1214</a>: fix handling of namespace packages when installing
from a wheel.</li>
</ul>
</div>
<div class="section" id="v38-2-1">
<h3>v38.2.1<a class="headerlink" href="#v38-2-1" title="Permalink to this headline">¶</a></h3>
<p>26 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1212">#1212</a>: fix encoding handling of metadata when installing
from a wheel.</li>
</ul>
</div>
<div class="section" id="v38-2-0">
<h3>v38.2.0<a class="headerlink" href="#v38-2-0" title="Permalink to this headline">¶</a></h3>
<p>26 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1200">#1200</a>: easy_install now support installing from wheels:
they will be installed as standalone unzipped eggs.</li>
</ul>
</div>
<div class="section" id="v38-1-0">
<h3>v38.1.0<a class="headerlink" href="#v38-1-0" title="Permalink to this headline">¶</a></h3>
<p>25 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1208">#1208</a>: Improve error message when failing to locate scripts
in egg-info metadata.</li>
</ul>
</div>
<div class="section" id="v38-0-0">
<h3>v38.0.0<a class="headerlink" href="#v38-0-0" title="Permalink to this headline">¶</a></h3>
<p>25 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/458">#458</a>: In order to support deterministic builds, Setuptools no
longer allows packages to declare <code class="docutils literal notranslate"><span class="pre">install_requires</span></code> as
unordered sequences (sets or dicts).</li>
</ul>
</div>
<div class="section" id="v37-0-0">
<h3>v37.0.0<a class="headerlink" href="#v37-0-0" title="Permalink to this headline">¶</a></h3>
<p>20 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/878">#878</a>: Drop support for Python 2.6. Python 2.6 users should
rely on ‘setuptools &lt; 37dev’.</li>
</ul>
</div>
<div class="section" id="v36-8-0">
<h3>v36.8.0<a class="headerlink" href="#v36-8-0" title="Permalink to this headline">¶</a></h3>
<p>19 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1190">#1190</a>: In SSL support for package index operations, use SNI
where available.</li>
</ul>
</div>
<div class="section" id="v36-7-3">
<h3>v36.7.3<a class="headerlink" href="#v36-7-3" title="Permalink to this headline">¶</a></h3>
<p>13 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1175">#1175</a>: Bug fixes to <code class="docutils literal notranslate"><span class="pre">build_meta</span></code> module.</li>
</ul>
</div>
<div class="section" id="v36-7-2">
<h3>v36.7.2<a class="headerlink" href="#v36-7-2" title="Permalink to this headline">¶</a></h3>
<p>13 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/701">#701</a>: Fixed duplicate test discovery on Python 3.</li>
</ul>
</div>
<div class="section" id="v36-7-1">
<h3>v36.7.1<a class="headerlink" href="#v36-7-1" title="Permalink to this headline">¶</a></h3>
<p>11 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1193">#1193</a>: Avoid test failures in bdist_egg when
PYTHONDONTWRITEBYTECODE is set.</li>
</ul>
</div>
<div class="section" id="v36-7-0">
<h3>v36.7.0<a class="headerlink" href="#v36-7-0" title="Permalink to this headline">¶</a></h3>
<p>09 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1054">#1054</a>: Support <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> files.</li>
</ul>
</div>
<div class="section" id="v36-6-1">
<h3>v36.6.1<a class="headerlink" href="#v36-6-1" title="Permalink to this headline">¶</a></h3>
<p>09 Nov 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1132">#1132</a>: Removed redundant and costly serialization/parsing step
in <code class="docutils literal notranslate"><span class="pre">EntryPoint.__init__</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/844">#844</a>: <code class="docutils literal notranslate"><span class="pre">bdist_egg</span> <span class="pre">--exclude-source-files</span></code> now tested and works
on Python 3.</li>
</ul>
</div>
<div class="section" id="v36-6-0">
<h3>v36.6.0<a class="headerlink" href="#v36-6-0" title="Permalink to this headline">¶</a></h3>
<p>12 Oct 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1143">#1143</a>: Added <code class="docutils literal notranslate"><span class="pre">setuptools.build_meta</span></code> module, an implementation
of <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP-517</a> for Setuptools-defined packages.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1143">#1143</a>: Added <code class="docutils literal notranslate"><span class="pre">dist_info</span></code> command for producing dist_info
metadata.</li>
</ul>
</div>
<div class="section" id="v36-5-0">
<h3>v36.5.0<a class="headerlink" href="#v36-5-0" title="Permalink to this headline">¶</a></h3>
<p>15 Sep 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/170">#170</a>: When working with Mercurial checkouts, use Windows-friendly
syntax for suppressing output.</li>
<li>Inspired by <a class="reference external" href="https://github.com/pypa/setuptools/issues/1134">#1134</a>, performed substantial refactoring of
<code class="docutils literal notranslate"><span class="pre">pkg_resources.find_on_path</span></code> to facilitate an optimization
for paths with many non-version entries.</li>
</ul>
</div>
<div class="section" id="v36-4-0">
<h3>v36.4.0<a class="headerlink" href="#v36-4-0" title="Permalink to this headline">¶</a></h3>
<p>03 Sep 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1075">#1075</a>: Add new <code class="docutils literal notranslate"><span class="pre">Description-Content-Type</span></code> metadata field. <a class="reference external" href="https://packaging.python.org/specifications/#description-content-type">See here for
documentation on how to use this field.</a></li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1068">#1068</a>: Sort files and directories when building eggs for
deterministic order.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/196">#196</a>: Remove caching of easy_install command in fetch_build_egg.
Fixes issue where <code class="docutils literal notranslate"><span class="pre">pytest-runner-N.N</span></code> would satisfy the installation
of <code class="docutils literal notranslate"><span class="pre">pytest</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1129">#1129</a>: Fix working set dependencies handling when replacing conflicting
distributions (e.g. when using <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> with a conflicting
transitive dependency, fix <a class="reference external" href="https://github.com/pypa/setuptools/issues/1124">#1124</a>).</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1133">#1133</a>: Improved handling of README files extensions and added
Markdown to the list of searched READMES.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1135">#1135</a>: Improve performance of pkg_resources import by not invoking
<code class="docutils literal notranslate"><span class="pre">access</span></code> or <code class="docutils literal notranslate"><span class="pre">stat</span></code> and using <code class="docutils literal notranslate"><span class="pre">os.listdir</span></code> instead.</li>
</ul>
</div>
<div class="section" id="v36-3-0">
<h3>v36.3.0<a class="headerlink" href="#v36-3-0" title="Permalink to this headline">¶</a></h3>
<p>28 Aug 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1131">#1131</a>: Make possible using several files within <code class="docutils literal notranslate"><span class="pre">file:</span></code> directive
in metadata.long_description in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>.</li>
</ul>
</div>
<div class="section" id="v36-2-7">
<h3>v36.2.7<a class="headerlink" href="#v36-2-7" title="Permalink to this headline">¶</a></h3>
<p>02 Aug 2017</p>
<ul class="simple">
<li>fix <a class="reference external" href="https://github.com/pypa/setuptools/issues/1105">#1105</a>: Fix handling of requirements with environment
markers when declared in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> (same treatment as
for <a class="reference external" href="https://github.com/pypa/setuptools/issues/1081">#1081</a>).</li>
</ul>
</div>
<div class="section" id="v36-2-6">
<h3>v36.2.6<a class="headerlink" href="#v36-2-6" title="Permalink to this headline">¶</a></h3>
<p>31 Jul 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/462">#462</a>: Don’t assume a directory is an egg by the <code class="docutils literal notranslate"><span class="pre">.egg</span></code>
extension alone.</li>
</ul>
</div>
<div class="section" id="v36-2-5">
<h3>v36.2.5<a class="headerlink" href="#v36-2-5" title="Permalink to this headline">¶</a></h3>
<p>30 Jul 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1093">#1093</a>: Fix test command handler with extras_require.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1112">#1112</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/1091">#1091</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/1115">#1115</a>: Now using Trusty containers in
Travis for CI and CD.</li>
</ul>
</div>
<div class="section" id="v36-2-4">
<h3>v36.2.4<a class="headerlink" href="#v36-2-4" title="Permalink to this headline">¶</a></h3>
<p>26 Jul 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1092">#1092</a>: <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> now uses <code class="docutils literal notranslate"><span class="pre">inspect.getmro</span></code> to
resolve classes in method resolution order.</li>
</ul>
</div>
<div class="section" id="v36-2-3">
<h3>v36.2.3<a class="headerlink" href="#v36-2-3" title="Permalink to this headline">¶</a></h3>
<p>25 Jul 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1102">#1102</a>: Restore behavior for empty extras.</li>
</ul>
</div>
<div class="section" id="v36-2-2">
<h3>v36.2.2<a class="headerlink" href="#v36-2-2" title="Permalink to this headline">¶</a></h3>
<p>24 Jul 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1099">#1099</a>: Revert commit a3ec721, restoring intended purpose of
extras as part of a requirement declaration.</li>
</ul>
</div>
<div class="section" id="v36-2-1">
<h3>v36.2.1<a class="headerlink" href="#v36-2-1" title="Permalink to this headline">¶</a></h3>
<p>23 Jul 2017</p>
<ul class="simple">
<li>fix <a class="reference external" href="https://github.com/pypa/setuptools/issues/1086">#1086</a></li>
<li>fix <a class="reference external" href="https://github.com/pypa/setuptools/issues/1087">#1087</a></li>
<li>support extras specifiers in install_requires requirements</li>
</ul>
</div>
<div class="section" id="v36-2-0">
<h3>v36.2.0<a class="headerlink" href="#v36-2-0" title="Permalink to this headline">¶</a></h3>
<p>13 Jul 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1081">#1081</a>: Environment markers indicated in <code class="docutils literal notranslate"><span class="pre">install_requires</span></code>
are now processed and treated as nameless <code class="docutils literal notranslate"><span class="pre">extras_require</span></code>
with markers, allowing their metadata in requires.txt to be
correctly generated.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1053">#1053</a>: Tagged commits are now released using Travis-CI
build stages, meaning releases depend on passing tests on
all supported Python versions (Linux) and not just the latest
Python version.</li>
</ul>
</div>
<div class="section" id="v36-1-1">
<h3>v36.1.1<a class="headerlink" href="#v36-1-1" title="Permalink to this headline">¶</a></h3>
<p>13 Jul 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1083">#1083</a>: Correct <code class="docutils literal notranslate"><span class="pre">py31compat.makedirs</span></code> to correctly honor
<code class="docutils literal notranslate"><span class="pre">exist_ok</span></code> parameter.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1083">#1083</a>: Also use makedirs compatibility throughout setuptools.</li>
</ul>
</div>
<div class="section" id="v36-1-0">
<h3>v36.1.0<a class="headerlink" href="#v36-1-0" title="Permalink to this headline">¶</a></h3>
<p>13 Jul 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1083">#1083</a>: Avoid race condition on directory creation in
<code class="docutils literal notranslate"><span class="pre">pkg_resources.ensure_directory</span></code>.</li>
<li>Removed deprecation of and restored support for
<code class="docutils literal notranslate"><span class="pre">upload_docs</span></code> command for sites other than PyPI.
Only warehouse is dropping support, but services like
<a class="reference external" href="http://doc.devpi.net/latest/">devpi</a> continue to
support docs built by setuptools’ plugins. See
<a class="reference external" href="https://bitbucket.org/hpk42/devpi/issues/388/support-rtd-model-for-building-uploading#comment-34292423">this comment</a>
for more context on the motivation for this change.</li>
</ul>
</div>
<div class="section" id="v36-0-1">
<h3>v36.0.1<a class="headerlink" href="#v36-0-1" title="Permalink to this headline">¶</a></h3>
<p>01 Jun 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1042">#1042</a>: Fix import in py27compat module that still
referenced six directly, rather than through the externs
module (vendored packages hook).</li>
</ul>
</div>
<div class="section" id="v36-0-0">
<h3>v36.0.0<a class="headerlink" href="#v36-0-0" title="Permalink to this headline">¶</a></h3>
<p>30 May 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/980">#980</a> and others: Once again, Setuptools vendors all
of its dependencies. It seems to be the case that in
the Python ecosystem, all build tools must run without
any dependencies (build, runtime, or otherwise). At
such a point that a mechanism exists that allows
build tools to have dependencies, Setuptools will adopt
it.</li>
</ul>
</div>
<div class="section" id="v35-0-2">
<h3>v35.0.2<a class="headerlink" href="#v35-0-2" title="Permalink to this headline">¶</a></h3>
<p>27 Apr 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1015">#1015</a>: Fix test failures on Python 3.7.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1024">#1024</a>: Add workaround for <a class="reference external" href="http://bugs.jython.org/issue2581">Jython #2581</a> in monkey module.</li>
</ul>
</div>
<div class="section" id="v35-0-1">
<h3>v35.0.1<a class="headerlink" href="#v35-0-1" title="Permalink to this headline">¶</a></h3>
<p>18 Apr 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/992">#992</a>: Revert change introduced in v34.4.1, now
considered invalid.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1016">#1016</a>: Revert change introduced in v35.0.0 per <a class="reference external" href="https://github.com/pypa/setuptools/issues/1014">#1014</a>,
referencing <a class="reference external" href="https://github.com/pypa/setuptools/issues/436">#436</a>. The approach had unintended
consequences, causing sdist installs to be missing
files.</li>
</ul>
</div>
<div class="section" id="v35-0-0">
<h3>v35.0.0<a class="headerlink" href="#v35-0-0" title="Permalink to this headline">¶</a></h3>
<p>15 Apr 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/436">#436</a>: In egg_info.manifest_maker, no longer read
the file list from the manifest file, and instead
re-build it on each build. In this way, files removed
from the specification will not linger in the manifest.
As a result, any files manually added to the manifest
will be removed on subsequent egg_info invocations.
No projects should be manually adding files to the
manifest and should instead use MANIFEST.in or SCM
file finders to force inclusion of files in the manifest.</li>
</ul>
</div>
<div class="section" id="v34-4-1">
<h3>v34.4.1<a class="headerlink" href="#v34-4-1" title="Permalink to this headline">¶</a></h3>
<p>10 Apr 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1008">#1008</a>: In MSVC support, use always the last version available for Windows SDK and UCRT SDK.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1008">#1008</a>: In MSVC support, fix “vcruntime140.dll” returned path with Visual Studio 2017.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/992">#992</a>: In msvc.msvc9_query_vcvarsall, ensure the
returned dicts have str values and not Unicode for
compatibility with os.environ.</li>
</ul>
</div>
<div class="section" id="v34-4-0">
<h3>v34.4.0<a class="headerlink" href="#v34-4-0" title="Permalink to this headline">¶</a></h3>
<p>07 Apr 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/995">#995</a>: In MSVC support, add support for “Microsoft Visual Studio 2017” and “Microsoft Visual Studio Build Tools 2017”.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/999">#999</a> via <a class="reference external" href="https://github.com/pypa/setuptools/issues/1007">#1007</a>: Extend support for declarative package
config in a setup.cfg file to include the options
<code class="docutils literal notranslate"><span class="pre">python_requires</span></code> and <code class="docutils literal notranslate"><span class="pre">py_modules</span></code>.</li>
</ul>
</div>
<div class="section" id="v34-3-3">
<h3>v34.3.3<a class="headerlink" href="#v34-3-3" title="Permalink to this headline">¶</a></h3>
<p>26 Mar 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/967">#967</a> (and <a class="reference external" href="https://github.com/pypa/setuptools/issues/997">#997</a>): Explicitly import submodules of
packaging to account for environments where the imports
of those submodules is not implied by other behavior.</li>
</ul>
</div>
<div class="section" id="v34-3-2">
<h3>v34.3.2<a class="headerlink" href="#v34-3-2" title="Permalink to this headline">¶</a></h3>
<p>11 Mar 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/993">#993</a>: Fix documentation upload by correcting
rendering of content-type in _build_multipart
on Python 3.</li>
</ul>
</div>
<div class="section" id="v34-3-1">
<h3>v34.3.1<a class="headerlink" href="#v34-3-1" title="Permalink to this headline">¶</a></h3>
<p>02 Mar 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/988">#988</a>: Trap <code class="docutils literal notranslate"><span class="pre">os.unlink</span></code> same as <code class="docutils literal notranslate"><span class="pre">os.remove</span></code> in
<code class="docutils literal notranslate"><span class="pre">auto_chmod</span></code> error handler.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/983">#983</a>: Fixes to invalid escape sequence deprecations on
Python 3.6.</li>
</ul>
</div>
<div class="section" id="v34-3-0">
<h3>v34.3.0<a class="headerlink" href="#v34-3-0" title="Permalink to this headline">¶</a></h3>
<p>23 Feb 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/941">#941</a>: In the upload command, if the username is blank,
default to <code class="docutils literal notranslate"><span class="pre">getpass.getuser()</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/971">#971</a>: Correct distutils findall monkeypatch to match
appropriate versions (namely Python 3.4.6).</li>
</ul>
</div>
<div class="section" id="v34-2-0">
<h3>v34.2.0<a class="headerlink" href="#v34-2-0" title="Permalink to this headline">¶</a></h3>
<p>12 Feb 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/966">#966</a>: Add support for reading dist-info metadata and
thus locating Distributions from zip files.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/968">#968</a>: Allow ‘+’ and ‘!’ in egg fragments
so that it can take package names that contain
<a class="reference external" href="https://www.python.org/dev/peps/pep-0440/">PEP 440</a> conforming version specifiers.</li>
</ul>
</div>
<div class="section" id="v34-1-1">
<h3>v34.1.1<a class="headerlink" href="#v34-1-1" title="Permalink to this headline">¶</a></h3>
<p>03 Feb 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/953">#953</a>: More aggressively employ the compatibility issue
originally added in <a class="reference external" href="https://github.com/pypa/setuptools/issues/706">#706</a>.</li>
</ul>
</div>
<div class="section" id="v34-1-0">
<h3>v34.1.0<a class="headerlink" href="#v34-1-0" title="Permalink to this headline">¶</a></h3>
<p>28 Jan 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/930">#930</a>: <code class="docutils literal notranslate"><span class="pre">build_info</span></code> now accepts two new parameters
to optimize and customize the building of C libraries.</li>
</ul>
</div>
<div class="section" id="v34-0-3">
<h3>v34.0.3<a class="headerlink" href="#v34-0-3" title="Permalink to this headline">¶</a></h3>
<p>28 Jan 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/947">#947</a>: Loosen restriction on the version of six required,
restoring compatibility with environments relying on
six 1.6.0 and later.</li>
</ul>
</div>
<div class="section" id="v34-0-2">
<h3>v34.0.2<a class="headerlink" href="#v34-0-2" title="Permalink to this headline">¶</a></h3>
<p>24 Jan 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/882">#882</a>: Ensure extras are honored when building the
working set.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/913">#913</a>: Fix issue in develop if package directory has
a trailing slash.</li>
</ul>
</div>
<div class="section" id="v34-0-1">
<h3>v34.0.1<a class="headerlink" href="#v34-0-1" title="Permalink to this headline">¶</a></h3>
<p>23 Jan 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/935">#935</a>: Fix glob syntax in graft.</li>
</ul>
</div>
<div class="section" id="v34-0-0">
<h3>v34.0.0<a class="headerlink" href="#v34-0-0" title="Permalink to this headline">¶</a></h3>
<p>23 Jan 2017</p>
<ul>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/581">#581</a>: Instead of vendoring the growing list of
dependencies that Setuptools requires to function,
Setuptools now requires these dependencies just like
any other project. Unlike other projects, however,
Setuptools cannot rely on <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> to
demand the dependencies it needs to install because
its own machinery would be necessary to pull those
dependencies if not present (a bootstrapping problem).
As a result, Setuptools no longer supports self upgrade or
installation in the general case. Instead, users are
directed to use pip to install and upgrade using the
<code class="docutils literal notranslate"><span class="pre">wheel</span></code> distributions of setuptools.</p>
<p>Users are welcome to contrive other means to install
or upgrade Setuptools using other means, such as
pre-installing the Setuptools dependencies with pip
or a bespoke bootstrap tool, but such usage is not
recommended and is not supported.</p>
<p>As discovered in <a class="reference external" href="https://github.com/pypa/setuptools/issues/940">#940</a>, not all versions of pip will
successfully install Setuptools from its pre-built
wheel. If you encounter issues with “No module named
six” or “No module named packaging”, especially
following a line “Running setup.py egg_info for package
setuptools”, then your pip is not new enough.</p>
<p>There’s an additional issue in pip where setuptools
is upgraded concurrently with other source packages,
described in pip <a class="reference external" href="https://github.com/pypa/setuptools/issues/4253">#4253</a>. The proposed workaround is to
always upgrade Setuptools first prior to upgrading
other packages that would upgrade Setuptools.</p>
</li>
</ul>
</div>
<div class="section" id="v33-1-1">
<h3>v33.1.1<a class="headerlink" href="#v33-1-1" title="Permalink to this headline">¶</a></h3>
<p>16 Jan 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/921">#921</a>: Correct issue where certifi fallback not being
reached on Windows.</li>
</ul>
</div>
<div class="section" id="v33-1-0">
<h3>v33.1.0<a class="headerlink" href="#v33-1-0" title="Permalink to this headline">¶</a></h3>
<p>15 Jan 2017</p>
<p>Installation via pip, as indicated in the <a class="reference external" href="https://packaging.python.org/installing/">Python Packaging
User’s Guide</a>,
is the officially-supported mechanism for installing
Setuptools, and this recommendation is now explicit in the
much more concise README.</p>
<p>Other edits and tweaks were made to the documentation. The
codebase is unchanged.</p>
</div>
<div class="section" id="v33-0-0">
<h3>v33.0.0<a class="headerlink" href="#v33-0-0" title="Permalink to this headline">¶</a></h3>
<p>01 Jan 2017</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/619">#619</a>: Removed support for the <code class="docutils literal notranslate"><span class="pre">tag_svn_revision</span></code>
distribution option. If Subversion tagging support is
still desired, consider adding the functionality to
setuptools_svn in <a class="reference external" href="https://github.com/jaraco/setuptools_svn/issues/2">setuptools_svn #2</a>.</li>
</ul>
</div>
<div class="section" id="v32-3-1">
<h3>v32.3.1<a class="headerlink" href="#v32-3-1" title="Permalink to this headline">¶</a></h3>
<p>28 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/866">#866</a>: Use <code class="docutils literal notranslate"><span class="pre">dis.Bytecode</span></code> on Python 3.4 and later in
<code class="docutils literal notranslate"><span class="pre">setuptools.depends</span></code>.</li>
</ul>
</div>
<div class="section" id="v32-3-0">
<h3>v32.3.0<a class="headerlink" href="#v32-3-0" title="Permalink to this headline">¶</a></h3>
<p>24 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/889">#889</a>: Backport proposed fix for disabling interpolation in
distutils.Distribution.parse_config_files.</li>
</ul>
</div>
<div class="section" id="v32-2-0">
<h3>v32.2.0<a class="headerlink" href="#v32-2-0" title="Permalink to this headline">¶</a></h3>
<p>22 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/884">#884</a>: Restore support for running the tests under
<a class="reference external" href="https://github.com/pytest-dev/pytest-runner">pytest-runner</a>
by ensuring that PYTHONPATH is honored in tests invoking
a subprocess.</li>
</ul>
</div>
<div class="section" id="v32-1-3">
<h3>v32.1.3<a class="headerlink" href="#v32-1-3" title="Permalink to this headline">¶</a></h3>
<p>21 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/706">#706</a>: Add rmtree compatibility shim for environments where
rmtree fails when passed a unicode string.</li>
</ul>
</div>
<div class="section" id="v32-1-2">
<h3>v32.1.2<a class="headerlink" href="#v32-1-2" title="Permalink to this headline">¶</a></h3>
<p>18 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/893">#893</a>: Only release sdist in zip format as warehouse now
disallows releasing two different formats.</li>
</ul>
</div>
<div class="section" id="v32-1-1">
<h3>v32.1.1<a class="headerlink" href="#v32-1-1" title="Permalink to this headline">¶</a></h3>
<p>18 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/704">#704</a>: More selectively ensure that ‘rmtree’ is not invoked with
a byte string, enabling it to remove files that are non-ascii,
even on Python 2.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/712">#712</a>: In ‘sandbox.run_setup’, ensure that <code class="docutils literal notranslate"><span class="pre">__file__</span></code> is
always a <code class="docutils literal notranslate"><span class="pre">str</span></code>, modeling the behavior observed by the
interpreter when invoking scripts and modules.</li>
</ul>
</div>
<div class="section" id="v32-1-0">
<h3>v32.1.0<a class="headerlink" href="#v32-1-0" title="Permalink to this headline">¶</a></h3>
<p>16 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/891">#891</a>: In ‘test’ command on test failure, raise DistutilsError,
suppression invocation of subsequent commands.</li>
</ul>
</div>
<div class="section" id="v32-0-0">
<h3>v32.0.0<a class="headerlink" href="#v32-0-0" title="Permalink to this headline">¶</a></h3>
<p>14 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/890">#890</a>: Revert <a class="reference external" href="https://github.com/pypa/setuptools/issues/849">#849</a>. <code class="docutils literal notranslate"><span class="pre">global-exclude</span> <span class="pre">.foo</span></code> will not match all
<code class="docutils literal notranslate"><span class="pre">*.foo</span></code> files any more. Package authors must add an explicit
wildcard, such as <code class="docutils literal notranslate"><span class="pre">global-exclude</span> <span class="pre">*.foo</span></code>, to match all
<code class="docutils literal notranslate"><span class="pre">.foo</span></code> files. See <a class="reference external" href="https://github.com/pypa/setuptools/issues/886">#886</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/849">#849</a>.</li>
</ul>
</div>
<div class="section" id="v31-0-1">
<h3>v31.0.1<a class="headerlink" href="#v31-0-1" title="Permalink to this headline">¶</a></h3>
<p>14 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/885">#885</a>: Fix regression where ‘pkg_resources._rebuild_mod_path’
would fail when a namespace package’s ‘__path__’ was not
a list with a sort attribute.</li>
</ul>
</div>
<div class="section" id="v31-0-0">
<h3>v31.0.0<a class="headerlink" href="#v31-0-0" title="Permalink to this headline">¶</a></h3>
<p>11 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/250">#250</a>: Install ‘-nspkg.pth’ files for packages installed
with ‘setup.py develop’. These .pth files allow
namespace packages installed by pip or develop to
co-mingle. This change required the removal of the
change for <a class="reference external" href="https://github.com/pypa/setuptools/issues/805">#805</a> and pip <a class="reference external" href="https://github.com/pypa/setuptools/issues/1924">#1924</a>, introduced in 28.3.0 and implicated
in <a class="reference external" href="https://github.com/pypa/setuptools/issues/870">#870</a>, but means that namespace packages not in a
site packages directory will no longer work on Python
earlier than 3.5, whereas before they would work on
Python not earlier than 3.3.</li>
</ul>
</div>
<div class="section" id="v30-4-0">
<h3>v30.4.0<a class="headerlink" href="#v30-4-0" title="Permalink to this headline">¶</a></h3>
<p>10 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/879">#879</a>: For declarative config:<ul>
<li>read_configuration() now accepts ignore_option_errors argument. This allows scraping tools to read metadata without a need to download entire packages. E.g. we can gather some stats right from GitHub repos just by downloading setup.cfg.</li>
<li>packages find: directive now supports fine tuning from a subsection. The same arguments as for find() are accepted.</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="v30-3-0">
<h3>v30.3.0<a class="headerlink" href="#v30-3-0" title="Permalink to this headline">¶</a></h3>
<p>08 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/394">#394</a> via <a class="reference external" href="https://github.com/pypa/setuptools/issues/862">#862</a>: Added support for <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files">declarative package
config in a setup.cfg file</a>.</li>
</ul>
</div>
<div class="section" id="v30-2-1">
<h3>v30.2.1<a class="headerlink" href="#v30-2-1" title="Permalink to this headline">¶</a></h3>
<p>08 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/850">#850</a>: In test command, invoke unittest.main with
indication not to exit the process.</li>
</ul>
</div>
<div class="section" id="v30-2-0">
<h3>v30.2.0<a class="headerlink" href="#v30-2-0" title="Permalink to this headline">¶</a></h3>
<p>04 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/854">#854</a>: Bump to vendored <a class="reference external" href="https://github.com/pypa/packaging/blob/16.8/CHANGELOG.rst">Packaging 16.8</a>.</li>
</ul>
</div>
<div class="section" id="v30-1-0">
<h3>v30.1.0<a class="headerlink" href="#v30-1-0" title="Permalink to this headline">¶</a></h3>
<p>03 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/846">#846</a>: Also trap ‘socket.error’ when opening URLs in
package_index.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/849">#849</a>: Manifest processing now matches the filename
pattern anywhere in the filename and not just at the
start. Restores behavior found prior to 28.5.0.</li>
</ul>
</div>
<div class="section" id="v30-0-0">
<h3>v30.0.0<a class="headerlink" href="#v30-0-0" title="Permalink to this headline">¶</a></h3>
<p>01 Dec 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/864">#864</a>: Drop support for Python 3.2. Systems requiring
Python 3.2 support must use ‘setuptools &lt; 30’.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/825">#825</a>: Suppress warnings for single files.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/830">#830</a> via <a class="reference external" href="https://github.com/pypa/setuptools/issues/843">#843</a>: Once again restored inclusion of data
files to sdists, but now trap TypeError caused by
techniques employed rjsmin and similar.</li>
</ul>
</div>
<div class="section" id="v29-0-1">
<h3>v29.0.1<a class="headerlink" href="#v29-0-1" title="Permalink to this headline">¶</a></h3>
<p>26 Nov 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/861">#861</a>: Re-release of v29.0.1 with the executable script
launchers bundled. Now, launchers are included by default
and users that want to disable this behavior must set the
environment variable
‘SETUPTOOLS_INSTALL_WINDOWS_SPECIFIC_FILES’ to
a false value like “false” or “0”.</li>
</ul>
</div>
<div class="section" id="v29-0-0">
<h3>v29.0.0<a class="headerlink" href="#v29-0-0" title="Permalink to this headline">¶</a></h3>
<p>25 Nov 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/841">#841</a>: Drop special exception for packages invoking
win32com during the build/install process. See
<a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/118">Distribute #118</a> for history.</li>
</ul>
</div>
<div class="section" id="v28-8-0">
<h3>v28.8.0<a class="headerlink" href="#v28-8-0" title="Permalink to this headline">¶</a></h3>
<p>04 Nov 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/629">#629</a>: Per the discussion, refine the sorting to use version
value order for more accurate detection of the latest
available version when scanning for packages. See also
<a class="reference external" href="https://github.com/pypa/setuptools/issues/829">#829</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/837">#837</a>: Rely on the config var “SO” for Python 3.3.0 only
when determining the ext filename.</li>
</ul>
</div>
<div class="section" id="v28-7-1">
<h3>v28.7.1<a class="headerlink" href="#v28-7-1" title="Permalink to this headline">¶</a></h3>
<p>29 Oct 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/827">#827</a>: Update PyPI root for dependency links.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/833">#833</a>: Backed out changes from <a class="reference external" href="https://github.com/pypa/setuptools/issues/830">#830</a> as the implementation
seems to have problems in some cases.</li>
</ul>
</div>
<div class="section" id="v28-7-0">
<h3>v28.7.0<a class="headerlink" href="#v28-7-0" title="Permalink to this headline">¶</a></h3>
<p>28 Oct 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/832">#832</a>: Moved much of the namespace package handling
functionality into a separate module for re-use in something
like <a class="reference external" href="https://github.com/pypa/setuptools/issues/789">#789</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/830">#830</a>: <code class="docutils literal notranslate"><span class="pre">sdist</span></code> command no longer suppresses the inclusion
of data files, re-aligning with the expectation of distutils
and addressing <a class="reference external" href="https://github.com/pypa/setuptools/issues/274">#274</a> and <a class="reference external" href="https://github.com/pypa/setuptools/issues/521">#521</a>.</li>
</ul>
</div>
<div class="section" id="v28-6-1">
<h3>v28.6.1<a class="headerlink" href="#v28-6-1" title="Permalink to this headline">¶</a></h3>
<p>19 Oct 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/816">#816</a>: Fix manifest file list order in tests.</li>
</ul>
</div>
<div class="section" id="v28-6-0">
<h3>v28.6.0<a class="headerlink" href="#v28-6-0" title="Permalink to this headline">¶</a></h3>
<p>16 Oct 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/629">#629</a>: When scanning for packages, <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> now
ignores empty egg-info directories and gives precedence to
packages whose versions are lexicographically greatest,
a rough approximation for preferring the latest available
version.</li>
</ul>
</div>
<div class="section" id="v28-5-0">
<h3>v28.5.0<a class="headerlink" href="#v28-5-0" title="Permalink to this headline">¶</a></h3>
<p>14 Oct 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/810">#810</a>: Tests are now invoked with tox and not setup.py test.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/249">#249</a> and <a class="reference external" href="https://github.com/pypa/setuptools/issues/450">#450</a> via <a class="reference external" href="https://github.com/pypa/setuptools/issues/764">#764</a>: Avoid scanning the whole tree
when building the manifest. Also fixes a long-standing bug
where patterns in <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> had implicit wildcard
matching. This caused <code class="docutils literal notranslate"><span class="pre">global-exclude</span> <span class="pre">.foo</span></code> to exclude
all <code class="docutils literal notranslate"><span class="pre">*.foo</span></code> files, but also <code class="docutils literal notranslate"><span class="pre">global-exclude</span> <span class="pre">bar.py</span></code> to
exclude <code class="docutils literal notranslate"><span class="pre">foo_bar.py</span></code>.</li>
</ul>
</div>
<div class="section" id="v28-4-0">
<h3>v28.4.0<a class="headerlink" href="#v28-4-0" title="Permalink to this headline">¶</a></h3>
<p>14 Oct 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/732">#732</a>: Now extras with a hyphen are honored per <a class="reference external" href="https://www.python.org/dev/peps/pep-0426/">PEP 426</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/811">#811</a>: Update to pyparsing 2.1.10.</li>
<li>Updated <code class="docutils literal notranslate"><span class="pre">setuptools.command.sdist</span></code> to re-use most of
the functionality directly from <code class="docutils literal notranslate"><span class="pre">distutils.command.sdist</span></code>
for the <code class="docutils literal notranslate"><span class="pre">add_defaults</span></code> method with strategic overrides.
See <a class="reference external" href="https://github.com/pypa/setuptools/issues/750">#750</a> for rationale.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/760">#760</a> via <a class="reference external" href="https://github.com/pypa/setuptools/issues/762">#762</a>: Look for certificate bundle where SUSE
Linux typically presents it. Use <code class="docutils literal notranslate"><span class="pre">certifi.where()</span></code> to locate
the bundle.</li>
</ul>
</div>
<div class="section" id="v28-3-0">
<h3>v28.3.0<a class="headerlink" href="#v28-3-0" title="Permalink to this headline">¶</a></h3>
<p>07 Oct 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/809">#809</a>: In <code class="docutils literal notranslate"><span class="pre">find_packages()</span></code>, restore support for excluding
a parent package without excluding a child package.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/805">#805</a>: Disable <code class="docutils literal notranslate"><span class="pre">-nspkg.pth</span></code> behavior on Python 3.3+ where
<a class="reference external" href="https://www.python.org/dev/peps/pep-0420/">PEP-420</a> functionality is adequate. Fixes pip <a class="reference external" href="https://github.com/pypa/setuptools/issues/1924">#1924</a>.</li>
</ul>
</div>
<div class="section" id="v28-1-0">
<h3>v28.1.0<a class="headerlink" href="#v28-1-0" title="Permalink to this headline">¶</a></h3>
<p>01 Oct 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/803">#803</a>: Bump certifi to 2016.9.26.</li>
</ul>
</div>
<div class="section" id="v28-0-0">
<h3>v28.0.0<a class="headerlink" href="#v28-0-0" title="Permalink to this headline">¶</a></h3>
<p>27 Sep 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/733">#733</a>: Do not search excluded directories for packages.
This introduced a backwards incompatible change in <code class="docutils literal notranslate"><span class="pre">find_packages()</span></code>
so that <code class="docutils literal notranslate"><span class="pre">find_packages(exclude=['foo'])</span> <span class="pre">==</span> <span class="pre">[]</span></code>, excluding subpackages of <code class="docutils literal notranslate"><span class="pre">foo</span></code>.
Previously, <code class="docutils literal notranslate"><span class="pre">find_packages(exclude=['foo'])</span> <span class="pre">==</span> <span class="pre">['foo.bar']</span></code>,
even though the parent <code class="docutils literal notranslate"><span class="pre">foo</span></code> package was excluded.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/795">#795</a>: Bump certifi.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/719">#719</a>: Suppress decoding errors and instead log a warning
when metadata cannot be decoded.</li>
</ul>
</div>
<div class="section" id="v27-3-1">
<h3>v27.3.1<a class="headerlink" href="#v27-3-1" title="Permalink to this headline">¶</a></h3>
<p>27 Sep 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/790">#790</a>: In MSVC monkeypatching, explicitly patch each
function by name in the target module instead of inferring
the module from the function’s <code class="docutils literal notranslate"><span class="pre">__module__</span></code>. Improves
compatibility with other packages that might have previously
patched distutils functions (i.e. NumPy).</li>
</ul>
</div>
<div class="section" id="v27-3-0">
<h3>v27.3.0<a class="headerlink" href="#v27-3-0" title="Permalink to this headline">¶</a></h3>
<p>20 Sep 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/794">#794</a>: In test command, add installed eggs to PYTHONPATH
when invoking tests so that subprocesses will also have the
dependencies available. Fixes <a class="reference external" href="https://github.com/tox-dev/tox/issues/330">tox 330</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/795">#795</a>: Update vendored pyparsing 2.1.9.</li>
</ul>
</div>
<div class="section" id="v27-2-0">
<h3>v27.2.0<a class="headerlink" href="#v27-2-0" title="Permalink to this headline">¶</a></h3>
<p>14 Sep 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/520">#520</a> and <a class="reference external" href="https://github.com/pypa/setuptools/issues/513">#513</a>: Suppress ValueErrors in fixup_namespace_packages
when lookup fails.</li>
<li>Nicer, more consistent interfaces for msvc monkeypatching.</li>
</ul>
</div>
<div class="section" id="v27-1-2">
<h3>v27.1.2<a class="headerlink" href="#v27-1-2" title="Permalink to this headline">¶</a></h3>
<p>09 Sep 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/779">#779</a> via <a class="reference external" href="https://github.com/pypa/setuptools/issues/781">#781</a>: Fix circular import.</li>
</ul>
</div>
<div class="section" id="v27-1-1">
<h3>v27.1.1<a class="headerlink" href="#v27-1-1" title="Permalink to this headline">¶</a></h3>
<p>09 Sep 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/778">#778</a>: Fix MSVC monkeypatching.</li>
</ul>
</div>
<div class="section" id="v27-1-0">
<h3>v27.1.0<a class="headerlink" href="#v27-1-0" title="Permalink to this headline">¶</a></h3>
<p>09 Sep 2016</p>
<ul class="simple">
<li>Introduce the (private) <code class="docutils literal notranslate"><span class="pre">monkey</span></code> module to encapsulate
the distutils monkeypatching behavior.</li>
</ul>
</div>
<div class="section" id="v27-0-0">
<h3>v27.0.0<a class="headerlink" href="#v27-0-0" title="Permalink to this headline">¶</a></h3>
<p>09 Sep 2016</p>
<ul>
<li><p class="first">Now use Warehouse by default for
<code class="docutils literal notranslate"><span class="pre">upload</span></code>, patching <code class="docutils literal notranslate"><span class="pre">distutils.config.PyPIRCCommand</span></code> to
affect default behavior.</p>
<p>Any config in .pypirc should be updated to replace</p>
<blockquote>
<div><p><a class="reference external" href="https://pypi.python.org/pypi/">https://pypi.python.org/pypi/</a></p>
</div></blockquote>
<p>with</p>
<blockquote>
<div><p><a class="reference external" href="https://upload.pypi.org/legacy/">https://upload.pypi.org/legacy/</a></p>
</div></blockquote>
<p>Similarly, any passwords stored in the keyring should be
updated to use this new value for “system”.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">upload_docs</span></code> command will continue to use the python.org
site, but the command is now deprecated. Users are urged to use
Read The Docs instead.</p>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/776">#776</a>: Use EXT_SUFFIX for py_limited_api renaming.</p>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/774">#774</a> and <a class="reference external" href="https://github.com/pypa/setuptools/issues/775">#775</a>: Use LegacyVersion from packaging when
detecting numpy versions.</p>
</li>
</ul>
</div>
<div class="section" id="v26-1-1">
<h3>v26.1.1<a class="headerlink" href="#v26-1-1" title="Permalink to this headline">¶</a></h3>
<p>29 Aug 2016</p>
<ul class="simple">
<li>Re-release of 26.1.0 with pytest pinned to allow for automated
deployment and thus proper packaging environment variables,
fixing issues with missing executable launchers.</li>
</ul>
</div>
<div class="section" id="v26-1-0">
<h3>v26.1.0<a class="headerlink" href="#v26-1-0" title="Permalink to this headline">¶</a></h3>
<p>28 Aug 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/763">#763</a>: <code class="docutils literal notranslate"><span class="pre">pkg_resources.get_default_cache</span></code> now defers to the
<a class="reference external" href="https://pypi.org/project/appdirs">appdirs project</a> to
resolve the cache directory. Adds a vendored dependency on
appdirs to pkg_resources.</li>
</ul>
</div>
<div class="section" id="v26-0-0">
<h3>v26.0.0<a class="headerlink" href="#v26-0-0" title="Permalink to this headline">¶</a></h3>
<p>20 Aug 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/748">#748</a>: By default, sdists are now produced in gzipped tarfile
format by default on all platforms, adding forward compatibility
for the same behavior in Python 3.6 (See <a class="reference external" href="http://bugs.python.org/issue27819">Python #27819</a>).</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/459">#459</a> via <a class="reference external" href="https://github.com/pypa/setuptools/issues/736">#736</a>: On Windows with script launchers,
sys.argv[0] now reflects
the name of the entry point, consistent with the behavior in
distlib and pip wrappers.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/752">#752</a> via <a class="reference external" href="https://github.com/pypa/setuptools/issues/753">#753</a>: When indicating <code class="docutils literal notranslate"><span class="pre">py_limited_api</span></code> to Extension,
it must be passed as a keyword argument.</li>
</ul>
</div>
<div class="section" id="v25-4-0">
<h3>v25.4.0<a class="headerlink" href="#v25-4-0" title="Permalink to this headline">¶</a></h3>
<p>19 Aug 2016</p>
<ul class="simple">
<li>Add Extension(py_limited_api=True). When set to a truthy value,
that extension gets a filename appropriate for code using Py_LIMITED_API.
When used correctly this allows a single compiled extension to work on
all future versions of CPython 3.
The py_limited_api argument only controls the filename. To be
compatible with multiple versions of Python 3, the C extension
will also need to set -DPy_LIMITED_API=… and be modified to use
only the functions in the limited API.</li>
</ul>
</div>
<div class="section" id="v25-3-0">
<h3>v25.3.0<a class="headerlink" href="#v25-3-0" title="Permalink to this headline">¶</a></h3>
<p>19 Aug 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/739">#739</a> Fix unquoted libpaths by fixing compatibility between <cite>numpy.distutils</cite> and <cite>distutils._msvccompiler</cite> for numpy &lt; 1.11.2 (Fix issue <a class="reference external" href="https://github.com/pypa/setuptools/issues/728">#728</a>, error also fixed in Numpy).</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/731">#731</a>: Bump certifi.</li>
<li>Style updates. See <a class="reference external" href="https://github.com/pypa/setuptools/issues/740">#740</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/741">#741</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/743">#743</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/744">#744</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/742">#742</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/747">#747</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/735">#735</a>: include license file.</li>
</ul>
</div>
<div class="section" id="v25-2-0">
<h3>v25.2.0<a class="headerlink" href="#v25-2-0" title="Permalink to this headline">¶</a></h3>
<p>12 Aug 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/612">#612</a> via <a class="reference external" href="https://github.com/pypa/setuptools/issues/730">#730</a>: Add a LICENSE file which needs to be provided by the terms of
the MIT license.</li>
</ul>
</div>
<div class="section" id="v25-1-6">
<h3>v25.1.6<a class="headerlink" href="#v25-1-6" title="Permalink to this headline">¶</a></h3>
<p>05 Aug 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/725">#725</a>: revert <cite>library_dir_option</cite> patch (Error is related to <cite>numpy.distutils</cite> and make errors on non Numpy users).</li>
</ul>
</div>
<div class="section" id="v25-1-5">
<h3>v25.1.5<a class="headerlink" href="#v25-1-5" title="Permalink to this headline">¶</a></h3>
<p>05 Aug 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/720">#720</a></li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/723">#723</a>: Improve patch for <cite>library_dir_option</cite>.</li>
</ul>
</div>
<div class="section" id="v25-1-4">
<h3>v25.1.4<a class="headerlink" href="#v25-1-4" title="Permalink to this headline">¶</a></h3>
<p>04 Aug 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/717">#717</a></li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/713">#713</a></li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/707">#707</a>: Fix Python 2 compatibility for MSVC by catching errors properly.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/715">#715</a>: Fix unquoted libpaths by patching <cite>library_dir_option</cite>.</li>
</ul>
</div>
<div class="section" id="v25-1-3">
<h3>v25.1.3<a class="headerlink" href="#v25-1-3" title="Permalink to this headline">¶</a></h3>
<p>02 Aug 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/714">#714</a> and <a class="reference external" href="https://github.com/pypa/setuptools/issues/704">#704</a>: Revert fix as it breaks other components
downstream that can’t handle unicode. See <a class="reference external" href="https://github.com/pypa/setuptools/issues/709">#709</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/710">#710</a>,
and <a class="reference external" href="https://github.com/pypa/setuptools/issues/712">#712</a>.</li>
</ul>
</div>
<div class="section" id="v25-1-2">
<h3>v25.1.2<a class="headerlink" href="#v25-1-2" title="Permalink to this headline">¶</a></h3>
<p>01 Aug 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/704">#704</a>: Fix errors when installing a zip sdist that contained
files named with non-ascii characters on Windows would
crash the install when it attempted to clean up the build.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/646">#646</a>: MSVC compatibility - catch errors properly in
RegistryInfo.lookup.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/702">#702</a>: Prevent UnboundLocalError when initial working_set
is empty.</li>
</ul>
</div>
<div class="section" id="v25-1-1">
<h3>v25.1.1<a class="headerlink" href="#v25-1-1" title="Permalink to this headline">¶</a></h3>
<p>28 Jul 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/686">#686</a>: Fix issue in sys.path ordering by pkg_resources when
rewrite technique is “raw”.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/699">#699</a>: Fix typo in msvc support.</li>
</ul>
</div>
<div class="section" id="v25-1-0">
<h3>v25.1.0<a class="headerlink" href="#v25-1-0" title="Permalink to this headline">¶</a></h3>
<p>25 Jul 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/609">#609</a>: Setuptools will now try to download a distribution from
the next possible download location if the first download fails.
This means you can now specify multiple links as <code class="docutils literal notranslate"><span class="pre">dependency_links</span></code>
and all links will be tried until a working download link is encountered.</li>
</ul>
</div>
<div class="section" id="v25-0-2">
<h3>v25.0.2<a class="headerlink" href="#v25-0-2" title="Permalink to this headline">¶</a></h3>
<p>25 Jul 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/688">#688</a>: Fix AttributeError in setup.py when invoked not from
the current directory.</li>
</ul>
</div>
<div class="section" id="v25-0-1">
<h3>v25.0.1<a class="headerlink" href="#v25-0-1" title="Permalink to this headline">¶</a></h3>
<p>25 Jul 2016</p>
<ul class="simple">
<li>Cleanup of setup.py script.</li>
<li>Fixed documentation builders by allowing setup.py
to be imported without having bootstrapped the
metadata.</li>
<li>More style cleanup. See <a class="reference external" href="https://github.com/pypa/setuptools/issues/677">#677</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/678">#678</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/679">#679</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/681">#681</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/685">#685</a>.</li>
</ul>
</div>
<div class="section" id="v25-0-0">
<h3>v25.0.0<a class="headerlink" href="#v25-0-0" title="Permalink to this headline">¶</a></h3>
<p>23 Jul 2016</p>
<ul>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/674">#674</a>: Default <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> manipulation by easy-install.pth
is now “raw”, meaning that when writing easy-install.pth
during any install operation, the <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> will not be
rewritten and will no longer give preference to easy_installed
packages.</p>
<p>To retain the old behavior when using any easy_install
operation (including <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">install</span></code> when setuptools is
present), set the environment variable:</p>
<blockquote>
<div><p>SETUPTOOLS_SYS_PATH_TECHNIQUE=rewrite</p>
</div></blockquote>
<p>This project hopes that that few if any environments find it
necessary to retain the old behavior, and intends to drop
support for it altogether in a future release. Please report
any relevant concerns in the ticket for this change.</p>
</li>
</ul>
</div>
<div class="section" id="v24-3-1">
<h3>v24.3.1<a class="headerlink" href="#v24-3-1" title="Permalink to this headline">¶</a></h3>
<p>23 Jul 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/398">#398</a>: Fix shebang handling on Windows in script
headers where spaces in <code class="docutils literal notranslate"><span class="pre">sys.executable</span></code> would
produce an improperly-formatted shebang header,
introduced in 12.0 with the fix for <a class="reference external" href="https://github.com/pypa/setuptools/issues/188">#188</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/663">#663</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/670">#670</a>: More style updates.</li>
</ul>
</div>
<div class="section" id="v24-3-0">
<h3>v24.3.0<a class="headerlink" href="#v24-3-0" title="Permalink to this headline">¶</a></h3>
<p>21 Jul 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/516">#516</a>: Disable <code class="docutils literal notranslate"><span class="pre">os.link</span></code> to avoid hard linking
in <code class="docutils literal notranslate"><span class="pre">sdist.make_distribution</span></code>, avoiding errors on
systems that support hard links but not on the
file system in which the build is occurring.</li>
</ul>
</div>
<div class="section" id="v24-2-1">
<h3>v24.2.1<a class="headerlink" href="#v24-2-1" title="Permalink to this headline">¶</a></h3>
<p>21 Jul 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/667">#667</a>: Update Metadata-Version to 1.2 when
<code class="docutils literal notranslate"><span class="pre">python_requires</span></code> is supplied.</li>
</ul>
</div>
<div class="section" id="v24-2-0">
<h3>v24.2.0<a class="headerlink" href="#v24-2-0" title="Permalink to this headline">¶</a></h3>
<p>20 Jul 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/631">#631</a>: Add support for <code class="docutils literal notranslate"><span class="pre">python_requires</span></code> keyword.</li>
</ul>
</div>
<div class="section" id="v24-1-1">
<h3>v24.1.1<a class="headerlink" href="#v24-1-1" title="Permalink to this headline">¶</a></h3>
<p>20 Jul 2016</p>
<ul class="simple">
<li>More style updates. See <a class="reference external" href="https://github.com/pypa/setuptools/issues/660">#660</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/661">#661</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/641">#641</a>.</li>
</ul>
</div>
<div class="section" id="v24-1-0">
<h3>v24.1.0<a class="headerlink" href="#v24-1-0" title="Permalink to this headline">¶</a></h3>
<p>20 Jul 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/659">#659</a>: <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> now will fail fast and with a helpful
error message when the necessary metadata is missing.</li>
<li>More style updates. See <a class="reference external" href="https://github.com/pypa/setuptools/issues/656">#656</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/635">#635</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/640">#640</a>,
<a class="reference external" href="https://github.com/pypa/setuptools/issues/644">#644</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/650">#650</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/652">#652</a>, and <a class="reference external" href="https://github.com/pypa/setuptools/issues/655">#655</a>.</li>
</ul>
</div>
<div class="section" id="v24-0-3">
<h3>v24.0.3<a class="headerlink" href="#v24-0-3" title="Permalink to this headline">¶</a></h3>
<p>14 Jul 2016</p>
<ul class="simple">
<li>Updated style in much of the codebase to match
community expectations. See <a class="reference external" href="https://github.com/pypa/setuptools/issues/632">#632</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/633">#633</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/634">#634</a>,
<a class="reference external" href="https://github.com/pypa/setuptools/issues/637">#637</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/639">#639</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/638">#638</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/642">#642</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/648">#648</a>.</li>
</ul>
</div>
<div class="section" id="v24-0-2">
<h3>v24.0.2<a class="headerlink" href="#v24-0-2" title="Permalink to this headline">¶</a></h3>
<p>04 Jul 2016</p>
<ul class="simple">
<li>If MSVC++14 is needed <code class="docutils literal notranslate"><span class="pre">setuptools.msvc</span></code> now redirect
user to Visual C++ Build Tools web page.</li>
</ul>
</div>
<div class="section" id="v24-0-1">
<h3>v24.0.1<a class="headerlink" href="#v24-0-1" title="Permalink to this headline">¶</a></h3>
<p>03 Jul 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/625">#625</a> and <a class="reference external" href="https://github.com/pypa/setuptools/issues/626">#626</a>: Fixes on <code class="docutils literal notranslate"><span class="pre">setuptools.msvc</span></code> mainly
for Python 2 and Linux.</li>
</ul>
</div>
<div class="section" id="v24-0-0">
<h3>v24.0.0<a class="headerlink" href="#v24-0-0" title="Permalink to this headline">¶</a></h3>
<p>02 Jul 2016</p>
<ul class="simple">
<li>Pull Request <a class="reference external" href="https://github.com/pypa/setuptools/issues/174">#174</a>: Add more aggressive support for
standalone Microsoft Visual C++ compilers in
msvc9compiler patch.
Particularly : Windows SDK 6.1 and 7.0
(MSVC++ 9.0), Windows SDK 7.1 (MSVC++ 10.0),
Visual C++ Build Tools 2015 (MSVC++14)</li>
<li>Renamed <code class="docutils literal notranslate"><span class="pre">setuptools.msvc9_support</span></code> to
<code class="docutils literal notranslate"><span class="pre">setuptools.msvc</span></code>.</li>
</ul>
</div>
<div class="section" id="v23-2-1">
<h3>v23.2.1<a class="headerlink" href="#v23-2-1" title="Permalink to this headline">¶</a></h3>
<p>02 Jul 2016</p>
<p>Re-release of v23.2.0, which was missing the intended
commits.</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/623">#623</a>: Remove used of deprecated ‘U’ flag when reading
manifests.</li>
</ul>
</div>
<div class="section" id="v23-1-0">
<h3>v23.1.0<a class="headerlink" href="#v23-1-0" title="Permalink to this headline">¶</a></h3>
<p>24 Jun 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/619">#619</a>: Deprecated <code class="docutils literal notranslate"><span class="pre">tag_svn_revision</span></code> distribution
option.</li>
</ul>
</div>
<div class="section" id="v23-0-0">
<h3>v23.0.0<a class="headerlink" href="#v23-0-0" title="Permalink to this headline">¶</a></h3>
<p>09 Jun 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/611">#611</a>: Removed ARM executables for CLI and GUI script
launchers on Windows. If this was a feature you cared
about, please comment in the ticket.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/604">#604</a>: Removed docs building support. The project
now relies on documentation hosted at
<a class="reference external" href="https://setuptools.readthedocs.io/">https://setuptools.readthedocs.io/</a>.</li>
</ul>
</div>
<div class="section" id="v22-0-5">
<h3>v22.0.5<a class="headerlink" href="#v22-0-5" title="Permalink to this headline">¶</a></h3>
<p>03 Jun 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/604">#604</a>: Restore repository for upload_docs command
to restore publishing of docs during release.</li>
</ul>
</div>
<div class="section" id="v22-0-4">
<h3>v22.0.4<a class="headerlink" href="#v22-0-4" title="Permalink to this headline">¶</a></h3>
<p>03 Jun 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/589">#589</a>: Upload releases to pypi.io using the upload
hostname and legacy path.</li>
</ul>
</div>
<div class="section" id="v22-0-3">
<h3>v22.0.3<a class="headerlink" href="#v22-0-3" title="Permalink to this headline">¶</a></h3>
<p>03 Jun 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/589">#589</a>: Releases are now uploaded to pypi.io (Warehouse)
even when releases are made on Twine via Travis.</li>
</ul>
</div>
<div class="section" id="v22-0-2">
<h3>v22.0.2<a class="headerlink" href="#v22-0-2" title="Permalink to this headline">¶</a></h3>
<p>03 Jun 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/589">#589</a>: Releases are now uploaded to pypi.io (Warehouse).</li>
</ul>
</div>
<div class="section" id="v22-0-1">
<h3>v22.0.1<a class="headerlink" href="#v22-0-1" title="Permalink to this headline">¶</a></h3>
<p>03 Jun 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/190">#190</a>: On Python 2, if unicode is passed for packages to
<code class="docutils literal notranslate"><span class="pre">build_py</span></code> command, it will be handled just as with
text on Python 3.</li>
</ul>
</div>
<div class="section" id="v22-0-0">
<h3>v22.0.0<a class="headerlink" href="#v22-0-0" title="Permalink to this headline">¶</a></h3>
<p>01 Jun 2016</p>
<p>Intended to be v21.3.0, but jaraco accidentally released as
a major bump.</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/598">#598</a>: Setuptools now lists itself first in the User-Agent
for web requests, better following the guidelines in
<a class="reference external" href="https://tools.ietf.org/html/rfc7231#section-5.5.3">RFC 7231</a>.</li>
</ul>
</div>
<div class="section" id="v21-2-2">
<h3>v21.2.2<a class="headerlink" href="#v21-2-2" title="Permalink to this headline">¶</a></h3>
<p>29 May 2016</p>
<ul class="simple">
<li>Minor fixes to changelog and docs.</li>
</ul>
</div>
<div class="section" id="v21-2-1">
<h3>v21.2.1<a class="headerlink" href="#v21-2-1" title="Permalink to this headline">¶</a></h3>
<p>22 May 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/261">#261</a>: Exclude directories when resolving globs in
package_data.</li>
</ul>
</div>
<div class="section" id="v21-2-0">
<h3>v21.2.0<a class="headerlink" href="#v21-2-0" title="Permalink to this headline">¶</a></h3>
<p>21 May 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/539">#539</a>: In the easy_install get_site_dirs, honor all
paths found in <code class="docutils literal notranslate"><span class="pre">site.getsitepackages</span></code>.</li>
</ul>
</div>
<div class="section" id="v21-1-0">
<h3>v21.1.0<a class="headerlink" href="#v21-1-0" title="Permalink to this headline">¶</a></h3>
<p>18 May 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/572">#572</a>: In build_ext, now always import <code class="docutils literal notranslate"><span class="pre">_CONFIG_VARS</span></code>
from <code class="docutils literal notranslate"><span class="pre">distutils</span></code> rather than from <code class="docutils literal notranslate"><span class="pre">sysconfig</span></code>
to allow <code class="docutils literal notranslate"><span class="pre">distutils.sysconfig.customize_compiler</span></code>
configure the OS X compiler for <code class="docutils literal notranslate"><span class="pre">-dynamiclib</span></code>.</li>
</ul>
</div>
<div class="section" id="v21-0-0">
<h3>v21.0.0<a class="headerlink" href="#v21-0-0" title="Permalink to this headline">¶</a></h3>
<p>02 May 2016</p>
<ul class="simple">
<li>Removed ez_setup.py from Setuptools sdist. The
bootstrap script will be maintained in its own
branch and should be generally be retrieved from
its canonical location at
<a class="reference external" href="https://bootstrap.pypa.io/ez_setup.py">https://bootstrap.pypa.io/ez_setup.py</a>.</li>
</ul>
</div>
<div class="section" id="v20-10-0">
<h3>v20.10.0<a class="headerlink" href="#v20-10-0" title="Permalink to this headline">¶</a></h3>
<p>25 Apr 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/553">#553</a>: egg_info section is now generated in a
deterministic order, matching the order generated
by earlier versions of Python. Except on Python 2.6,
order is preserved when existing settings are present.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/556">#556</a>: Update to <a class="reference external" href="https://github.com/pypa/packaging/blob/16.7/CHANGELOG.rst">Packaging 16.7</a>, restoring support
for deprecated <code class="docutils literal notranslate"><span class="pre">python_implmentation</span></code> marker.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/555">#555</a>: Upload command now prompts for a password
when uploading to PyPI (or other repository) if no
password is present in .pypirc or in the keyring.</li>
</ul>
</div>
<div class="section" id="v20-9-0">
<h3>v20.9.0<a class="headerlink" href="#v20-9-0" title="Permalink to this headline">¶</a></h3>
<p>16 Apr 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/548">#548</a>: Update certify version to 2016.2.28</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/545">#545</a>: Safely handle deletion of non-zip eggs in rotate
command.</li>
</ul>
</div>
<div class="section" id="v20-8-1">
<h3>v20.8.1<a class="headerlink" href="#v20-8-1" title="Permalink to this headline">¶</a></h3>
<p>15 Apr 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/544">Issue #544</a>: Fix issue with extra environment marker
processing in WorkingSet due to refactor in v20.7.0.</li>
</ul>
</div>
<div class="section" id="v20-8-0">
<h3>v20.8.0<a class="headerlink" href="#v20-8-0" title="Permalink to this headline">¶</a></h3>
<p>15 Apr 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/543">Issue #543</a>: Re-release so that latest release doesn’t
cause déjà vu with distribute and setuptools 0.7 in
older environments.</li>
</ul>
</div>
<div class="section" id="v20-7-0">
<h3>v20.7.0<a class="headerlink" href="#v20-7-0" title="Permalink to this headline">¶</a></h3>
<p>10 Apr 2016</p>
<ul class="simple">
<li>Refactored extra environment marker processing
in WorkingSet.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/533">Issue #533</a>: Fixed intermittent test failures.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/536">Issue #536</a>: In msvc9_support, trap additional exceptions
that might occur when importing
<code class="docutils literal notranslate"><span class="pre">distutils.msvc9compiler</span></code> in mingw environments.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/537">Issue #537</a>: Provide better context when package
metadata fails to decode in UTF-8.</li>
</ul>
</div>
<div class="section" id="v20-6-8">
<h3>v20.6.8<a class="headerlink" href="#v20-6-8" title="Permalink to this headline">¶</a></h3>
<p>09 May 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/523">Issue #523</a>: Restored support for environment markers,
now honoring ‘extra’ environment markers.</li>
</ul>
</div>
<div class="section" id="v20-6-7">
<h3>v20.6.7<a class="headerlink" href="#v20-6-7" title="Permalink to this headline">¶</a></h3>
<p>31 Mar 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/523">Issue #523</a>: Disabled support for environment markers
introduced in v20.5.</li>
</ul>
</div>
<div class="section" id="v20-6-6">
<h3>v20.6.6<a class="headerlink" href="#v20-6-6" title="Permalink to this headline">¶</a></h3>
<p>30 Mar 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/503">Issue #503</a>: Restore support for <a class="reference external" href="https://www.python.org/dev/peps/pep-0345/">PEP 345</a> environment
markers by updating to <a class="reference external" href="https://github.com/pypa/packaging/blob/16.6/CHANGELOG.rst">Packaging 16.6</a>.</li>
</ul>
</div>
<div class="section" id="v20-6-0">
<h3>v20.6.0<a class="headerlink" href="#v20-6-0" title="Permalink to this headline">¶</a></h3>
<p>29 Mar 2016</p>
<ul class="simple">
<li>New release process that relies on
<a class="reference external" href="https://github.com/peritus/bumpversion">bumpversion</a>
and Travis CI for continuous deployment.</li>
<li>Project versioning semantics now follow
<a class="reference external" href="https://semver.org">semver</a> precisely.
The ‘v’ prefix on version numbers now also allows
version numbers to be referenced in the changelog,
e.g. <a class="reference external" href="http://setuptools.readthedocs.io/en/latest/history.html#v20-6-0">http://setuptools.readthedocs.io/en/latest/history.html#v20-6-0</a>.</li>
</ul>
</div>
<div class="section" id="id430">
<h3>20.5<a class="headerlink" href="#id430" title="Permalink to this headline">¶</a></h3>
<p>29 Mar 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/185">BB Pull Request #185</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/470">#470</a>: Add support for environment markers
in requirements in install_requires, setup_requires,
tests_require as well as adding a test for the existing
extra_requires machinery.</li>
</ul>
</div>
<div class="section" id="id432">
<h3>20.4<a class="headerlink" href="#id432" title="Permalink to this headline">¶</a></h3>
<p>29 Mar 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/422">Issue #422</a>: Moved hosting to
<a class="reference external" href="https://github.com/pypa/setuptools">Github</a>
from <a class="reference external" href="https://bitbucket.org/pypa/setuptools">Bitbucket</a>.
Issues have been migrated, though all issues and comments
are attributed to bb-migration. So if you have a particular
issue or issues to which you’ve been subscribed, you will
want to “watch” the equivalent issue in Github.
The Bitbucket project will be retained for the indefinite
future, but Github now hosts the canonical project repository.</li>
</ul>
</div>
<div class="section" id="id433">
<h3>20.3.1<a class="headerlink" href="#id433" title="Permalink to this headline">¶</a></h3>
<p>18 Mar 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/519">Issue #519</a>: Remove import hook when reloading the
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module.</li>
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/184">BB Pull Request #184</a>: Update documentation in <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>
around new <code class="docutils literal notranslate"><span class="pre">Requirement</span></code> implementation.</li>
</ul>
</div>
<div class="section" id="id434">
<h3>20.3<a class="headerlink" href="#id434" title="Permalink to this headline">¶</a></h3>
<p>15 Mar 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/179">BB Pull Request #179</a>: <code class="docutils literal notranslate"><span class="pre">pkg_resources.Requirement</span></code> objects are
now a subclass of <code class="docutils literal notranslate"><span class="pre">packaging.requirements.Requirement</span></code>,
allowing any environment markers and url (if any) to be
affiliated with the requirement</li>
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/179">BB Pull Request #179</a>: Restore use of RequirementParseError
exception unintentionally dropped in 20.2.</li>
</ul>
</div>
<div class="section" id="id436">
<h3>20.2.2<a class="headerlink" href="#id436" title="Permalink to this headline">¶</a></h3>
<p>27 Feb 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/502">Issue #502</a>: Correct regression in parsing of multiple
version specifiers separated by commas and spaces.</li>
</ul>
</div>
<div class="section" id="id437">
<h3>20.2.1<a class="headerlink" href="#id437" title="Permalink to this headline">¶</a></h3>
<p>24 Feb 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/499">Issue #499</a>: Restore compatibility for legacy versions
by bumping to <a class="reference external" href="https://github.com/pypa/packaging/blob/16.4/CHANGELOG.rst">packaging 16.4</a>.</li>
</ul>
</div>
<div class="section" id="id438">
<h3>20.2<a class="headerlink" href="#id438" title="Permalink to this headline">¶</a></h3>
<p>19 Feb 2016</p>
<ul>
<li><p class="first">Changelog now includes release dates and links to PEPs.</p>
</li>
<li><p class="first"><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/173">BB Pull Request #173</a>: Replace dual <a class="reference external" href="https://www.python.org/dev/peps/pep-0345/">PEP 345</a> _markerlib implementation
and <a class="reference external" href="https://www.python.org/dev/peps/pep-0426/">PEP 426</a> implementation of environment marker support from
<a class="reference external" href="https://github.com/pypa/packaging/blob/16.1/CHANGELOG.rst">packaging 16.1</a> and <a class="reference external" href="https://www.python.org/dev/peps/pep-0508/">PEP 508</a>. Fixes <a class="reference external" href="https://github.com/pypa/setuptools/issues/122">Issue #122</a>.
See also <a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/175">BB Pull Request #175</a>, <a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/168">BB Pull Request #168</a>, and
<a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/164">BB Pull Request #164</a>. Additionally:</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">Requirement.parse</span></code> no longer retains the order of extras.</li>
<li><code class="docutils literal notranslate"><span class="pre">parse_requirements</span></code> now requires that all versions be
<a class="reference external" href="https://www.python.org/dev/peps/pep-0440/">PEP-440</a> compliant, as revealed in <a class="reference external" href="https://github.com/pypa/setuptools/issues/499">#499</a>. Packages released
with invalid local versions should be re-released using
the proper local version syntax, e.g. <code class="docutils literal notranslate"><span class="pre">mypkg-1.0+myorg.1</span></code>.</li>
</ul>
</div></blockquote>
</li>
</ul>
</div>
<div class="section" id="id444">
<h3>20.1.1<a class="headerlink" href="#id444" title="Permalink to this headline">¶</a></h3>
<p>12 Feb 2016</p>
<ul class="simple">
<li>Update <code class="docutils literal notranslate"><span class="pre">upload_docs</span></code> command to also honor keyring
for password resolution.</li>
</ul>
</div>
<div class="section" id="id445">
<h3>20.1<a class="headerlink" href="#id445" title="Permalink to this headline">¶</a></h3>
<p>11 Feb 2016</p>
<ul class="simple">
<li>Added support for using passwords from keyring in the upload
command. See <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#upload-upload-source-and-or-egg-distributions-to-pypi">the upload docs</a>
for details.</li>
</ul>
</div>
<div class="section" id="id446">
<h3>20.0<a class="headerlink" href="#id446" title="Permalink to this headline">¶</a></h3>
<p>07 Feb 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/118">Issue #118</a>: Once again omit the package metadata (egg-info)
from the list of outputs in <code class="docutils literal notranslate"><span class="pre">--record</span></code>. This version of setuptools
can no longer be used to upgrade pip earlier than 6.0.</li>
</ul>
</div>
<div class="section" id="id447">
<h3>19.7<a class="headerlink" href="#id447" title="Permalink to this headline">¶</a></h3>
<p>03 Feb 2016</p>
<ul class="simple">
<li>Off-project PR: <a class="reference external" href="https://github.com/pypa/setuptools/commit/0dcee791dfdcfacddaaec79b29f30a347a147413">0dcee79</a> and <a class="reference external" href="https://github.com/pypa/setuptools/commit/f9bd9b9f5df54ef5a0bf8d16c3a889ab8c640580">f9bd9b9</a>
For FreeBSD, also <a class="reference external" href="https://github.com/pypa/setuptools/commit/3ae46c30225eb46e1f5aada1a19e88b79f04dc72">honor root certificates from ca_root_nss</a>.</li>
</ul>
</div>
<div class="section" id="id448">
<h3>19.6.2<a class="headerlink" href="#id448" title="Permalink to this headline">¶</a></h3>
<p>31 Jan 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/491">Issue #491</a>: Correct regression incurred in 19.4 where
a double-namespace package installed using pip would
cause a TypeError.</li>
</ul>
</div>
<div class="section" id="id449">
<h3>19.6.1<a class="headerlink" href="#id449" title="Permalink to this headline">¶</a></h3>
<p>29 Jan 2016</p>
<ul class="simple">
<li>Restore compatibility for PyPy 3 compatibility lost in
19.4.1 addressing <a class="reference external" href="https://github.com/pypa/setuptools/issues/487">Issue #487</a>.</li>
<li><code class="docutils literal notranslate"><span class="pre">setuptools.launch</span></code> shim now loads scripts in a new
namespace, avoiding getting relative imports from
the setuptools package on Python 2.</li>
</ul>
</div>
<div class="section" id="id450">
<h3>19.6<a class="headerlink" href="#id450" title="Permalink to this headline">¶</a></h3>
<p>24 Jan 2016</p>
<ul>
<li><p class="first">Added a new entry script <code class="docutils literal notranslate"><span class="pre">setuptools.launch</span></code>,
implementing the shim found in
<code class="docutils literal notranslate"><span class="pre">pip.util.setuptools_build</span></code>. Use this command to launch
distutils-only packages under setuptools in the same way that
pip does, causing the setuptools monkeypatching of distutils
to be invoked prior to invoking a script. Useful for debugging
or otherwise installing a distutils-only package under
setuptools when pip isn’t available or otherwise does not
expose the desired functionality. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python -m setuptools.launch setup.py develop
</pre></div>
</div>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/488">Issue #488</a>: Fix dual manifestation of Extension class in
extension packages installed as dependencies when Cython
is present.</p>
</li>
</ul>
</div>
<div class="section" id="id451">
<h3>19.5<a class="headerlink" href="#id451" title="Permalink to this headline">¶</a></h3>
<p>23 Jan 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/486">Issue #486</a>: Correct TypeError when getfilesystemencoding
returns None.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/139">Issue #139</a>: Clarified the license as MIT.</li>
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/169">BB Pull Request #169</a>: Removed special handling of command
spec in scripts for Jython.</li>
</ul>
</div>
<div class="section" id="id452">
<h3>19.4.1<a class="headerlink" href="#id452" title="Permalink to this headline">¶</a></h3>
<p>23 Jan 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/487">Issue #487</a>: Use direct invocation of <code class="docutils literal notranslate"><span class="pre">importlib.machinery</span></code>
in <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> to avoid missing detection on relevant
platforms.</li>
</ul>
</div>
<div class="section" id="id454">
<h3>19.4<a class="headerlink" href="#id454" title="Permalink to this headline">¶</a></h3>
<p>16 Jan 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/341">Issue #341</a>: Correct error in path handling of package data
files in <code class="docutils literal notranslate"><span class="pre">build_py</span></code> command when package is empty.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/323">Distribute #323</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/141">Issue #141</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/207">Issue #207</a>, and
<a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/167">BB Pull Request #167</a>: Another implementation of
<code class="docutils literal notranslate"><span class="pre">pkg_resources.WorkingSet</span></code> and <code class="docutils literal notranslate"><span class="pre">pkg_resources.Distribution</span></code>
that supports replacing an extant package with a new one,
allowing for setup_requires dependencies to supersede installed
packages for the session.</li>
</ul>
</div>
<div class="section" id="id455">
<h3>19.3<a class="headerlink" href="#id455" title="Permalink to this headline">¶</a></h3>
<p>06 Jan 2016</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/229">Issue #229</a>: Implement new technique for readily incorporating
dependencies conditionally from vendored copies or primary
locations. Adds a new dependency on six.</li>
</ul>
</div>
<div class="section" id="id456">
<h3>19.2<a class="headerlink" href="#id456" title="Permalink to this headline">¶</a></h3>
<p>25 Dec 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/163">BB Pull Request #163</a>: Add get_command_list method to Distribution.</li>
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/162">BB Pull Request #162</a>: Add missing whitespace to multiline string
literals.</li>
</ul>
</div>
<div class="section" id="id457">
<h3>19.1.1<a class="headerlink" href="#id457" title="Permalink to this headline">¶</a></h3>
<p>16 Dec 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/476">Issue #476</a>: Cast version to string (using default encoding)
to avoid creating Unicode types on Python 2 clients.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/477">Issue #477</a>: In Powershell downloader, use explicit rendering
of strings, rather than rely on <code class="docutils literal notranslate"><span class="pre">repr</span></code>, which can be
incorrect (especially on Python 2).</li>
</ul>
</div>
<div class="section" id="id458">
<h3>19.1<a class="headerlink" href="#id458" title="Permalink to this headline">¶</a></h3>
<p>16 Dec 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/215">Issue #215</a>: The bootstrap script <code class="docutils literal notranslate"><span class="pre">ez_setup.py</span></code> now
automatically detects
the latest version of setuptools (using PyPI JSON API) rather
than hard-coding a particular value.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/475">Issue #475</a>: Fix incorrect usage in _translate_metadata2.</li>
</ul>
</div>
<div class="section" id="id459">
<h3>19.0<a class="headerlink" href="#id459" title="Permalink to this headline">¶</a></h3>
<p>15 Dec 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/442">Issue #442</a>: Use RawConfigParser for parsing .pypirc file.
Interpolated values are no longer honored in .pypirc files.</li>
</ul>
</div>
<div class="section" id="id460">
<h3>18.8.1<a class="headerlink" href="#id460" title="Permalink to this headline">¶</a></h3>
<p>13 Dec 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/440">Issue #440</a>: Prevent infinite recursion when a SandboxViolation
or other UnpickleableException occurs in a sandbox context
with setuptools hidden. Fixes regression introduced in Setuptools
12.0.</li>
</ul>
</div>
<div class="section" id="id461">
<h3>18.8<a class="headerlink" href="#id461" title="Permalink to this headline">¶</a></h3>
<p>11 Dec 2015</p>
<ul class="simple">
<li>Deprecated <code class="docutils literal notranslate"><span class="pre">egg_info.get_pkg_info_revision</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/471">Issue #471</a>: Don’t rely on repr for an HTML attribute value in
package_index.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/419">Issue #419</a>: Avoid errors in FileMetadata when the metadata directory
is broken.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/472">Issue #472</a>: Remove deprecated use of ‘U’ in mode parameter
when opening files.</li>
</ul>
</div>
<div class="section" id="id462">
<h3>18.7.1<a class="headerlink" href="#id462" title="Permalink to this headline">¶</a></h3>
<p>01 Dec 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/469">Issue #469</a>: Refactored logic for <a class="reference external" href="https://github.com/pypa/setuptools/issues/419">Issue #419</a> fix to re-use metadata
loading from Provider.</li>
</ul>
</div>
<div class="section" id="id464">
<h3>18.7<a class="headerlink" href="#id464" title="Permalink to this headline">¶</a></h3>
<p>28 Nov 2015</p>
<ul class="simple">
<li>Update dependency on certify.</li>
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/160">BB Pull Request #160</a>: Improve detection of gui script in
<code class="docutils literal notranslate"><span class="pre">easy_install._adjust_header</span></code>.</li>
<li>Made <code class="docutils literal notranslate"><span class="pre">test.test_args</span></code> a non-data property; alternate fix
for the issue reported in <a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/155">BB Pull Request #155</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/453">Issue #453</a>: In <code class="docutils literal notranslate"><span class="pre">ez_setup</span></code> bootstrap module, unload all
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> modules following download.</li>
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/158">BB Pull Request #158</a>: Honor <a class="reference external" href="https://www.python.org/dev/peps/pep-0488/">PEP-488</a> when excluding
files for namespace packages.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/419">Issue #419</a> and <a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/144">BB Pull Request #144</a>: Add experimental support for
reading the version info from distutils-installed metadata rather
than using the version in the filename.</li>
</ul>
</div>
<div class="section" id="id466">
<h3>18.6.1<a class="headerlink" href="#id466" title="Permalink to this headline">¶</a></h3>
<p>24 Nov 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/464">Issue #464</a>: Correct regression in invocation of superclass on old-style
class on Python 2.</li>
</ul>
</div>
<div class="section" id="id467">
<h3>18.6<a class="headerlink" href="#id467" title="Permalink to this headline">¶</a></h3>
<p>24 Nov 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/439">Issue #439</a>: When installing entry_point scripts under development,
omit the version number of the package, allowing any version of the
package to be used.</li>
</ul>
</div>
<div class="section" id="id468">
<h3>18.5<a class="headerlink" href="#id468" title="Permalink to this headline">¶</a></h3>
<p>01 Nov 2015</p>
<ul class="simple">
<li>In preparation for dropping support for Python 3.2, a warning is
now logged when pkg_resources is imported on Python 3.2 or earlier
Python 3 versions.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/commit/94416707fd59a65f4a8f7f70541d6b3fc018b626">Add support for python_platform_implementation environment marker</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/commit/57ebfa41e0f96b97e599ecd931b7ae8a143e096e">Fix dictionary mutation during iteration</a>.</li>
</ul>
</div>
<div class="section" id="id469">
<h3>18.4<a class="headerlink" href="#id469" title="Permalink to this headline">¶</a></h3>
<p>10 Oct 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/446">Issue #446</a>: Test command now always invokes unittest, even
if no test suite is supplied.</li>
</ul>
</div>
<div class="section" id="id470">
<h3>18.3.2<a class="headerlink" href="#id470" title="Permalink to this headline">¶</a></h3>
<p>19 Sep 2015</p>
<ul class="simple">
<li>Correct another regression in setuptools.findall
where the fix for <a class="reference external" href="http://bugs.python.org/issue12885">Python #12885</a> was lost.</li>
</ul>
</div>
<div class="section" id="id471">
<h3>18.3.1<a class="headerlink" href="#id471" title="Permalink to this headline">¶</a></h3>
<p>07 Sep 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/425">Issue #425</a>: Correct regression in setuptools.findall.</li>
</ul>
</div>
<div class="section" id="id472">
<h3>18.3<a class="headerlink" href="#id472" title="Permalink to this headline">¶</a></h3>
<p>06 Sep 2015</p>
<ul>
<li><p class="first"><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/135">BB Pull Request #135</a>: Setuptools now allows disabling of
the manipulation of the sys.path
during the processing of the easy-install.pth file. To do so, set
the environment variable <code class="docutils literal notranslate"><span class="pre">SETUPTOOLS_SYS_PATH_TECHNIQUE</span></code> to
anything but “rewrite” (consider “raw”). During any install operation
with manipulation disabled, setuptools packages will be appended to
sys.path naturally.</p>
<p>Future versions may change the default behavior to disable
manipulation. If so, the default behavior can be retained by setting
the variable to “rewrite”.</p>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/257">Issue #257</a>: <code class="docutils literal notranslate"><span class="pre">easy_install</span> <span class="pre">--version</span></code> now shows more detail
about the installation location and Python version.</p>
</li>
<li><p class="first">Refactor setuptools.findall in preparation for re-submission
back to distutils.</p>
</li>
</ul>
</div>
<div class="section" id="id473">
<h3>18.2<a class="headerlink" href="#id473" title="Permalink to this headline">¶</a></h3>
<p>19 Aug 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/412">Issue #412</a>: More efficient directory search in <code class="docutils literal notranslate"><span class="pre">find_packages</span></code>.</li>
</ul>
</div>
<div class="section" id="id474">
<h3>18.1<a class="headerlink" href="#id474" title="Permalink to this headline">¶</a></h3>
<p>02 Aug 2015</p>
<ul class="simple">
<li>Upgrade to vendored <a class="reference external" href="https://github.com/pypa/packaging/blob/15.3/CHANGELOG.rst">packaging 15.3</a>.</li>
</ul>
</div>
<div class="section" id="id475">
<h3>18.0.1<a class="headerlink" href="#id475" title="Permalink to this headline">¶</a></h3>
<p>24 Jun 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/401">Issue #401</a>: Fix failure in test suite.</li>
</ul>
</div>
<div class="section" id="id476">
<h3>18.0<a class="headerlink" href="#id476" title="Permalink to this headline">¶</a></h3>
<p>13 Jun 2015</p>
<ul>
<li><p class="first">Dropped support for builds with Pyrex. Only Cython is supported.</p>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/288">Issue #288</a>: Detect Cython later in the build process, after
<code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> dependencies are resolved.
Projects backed by Cython can now be readily built
with a <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> dependency. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ext</span> <span class="o">=</span> <span class="n">setuptools</span><span class="o">.</span><span class="n">Extension</span><span class="p">(</span><span class="s1">&#39;mylib&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;src/CythonStuff.pyx&#39;</span><span class="p">,</span> <span class="s1">&#39;src/CStuff.c&#39;</span><span class="p">])</span>
<span class="n">setuptools</span><span class="o">.</span><span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">ext</span><span class="p">],</span>
    <span class="n">setup_requires</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;cython&#39;</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>For compatibility with older versions of setuptools, packagers should
still include <code class="docutils literal notranslate"><span class="pre">src/CythonMod.c</span></code> in the source distributions or
require that Cython be present before building source distributions.
However, for systems with this build of setuptools, Cython will be
downloaded on demand.</p>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/396">Issue #396</a>: Fixed test failure on OS X.</p>
</li>
<li><p class="first"><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/136">BB Pull Request #136</a>: Remove excessive quoting from shebang headers
for Jython.</p>
</li>
</ul>
</div>
<div class="section" id="id477">
<h3>17.1.1<a class="headerlink" href="#id477" title="Permalink to this headline">¶</a></h3>
<p>08 Jun 2015</p>
<ul class="simple">
<li>Backed out unintended changes to pkg_resources, restoring removal of
deprecated imp module (<a class="reference external" href="https://bitbucket.org/pypa/setuptools/commits/f572ec9563d647fa8d4ffc534f2af8070ea07a8b#comment-1881283">ref</a>).</li>
</ul>
</div>
<div class="section" id="id478">
<h3>17.1<a class="headerlink" href="#id478" title="Permalink to this headline">¶</a></h3>
<p>07 Jun 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/380">Issue #380</a>: Add support for range operators on environment
marker evaluation.</li>
</ul>
</div>
<div class="section" id="id479">
<h3>17.0<a class="headerlink" href="#id479" title="Permalink to this headline">¶</a></h3>
<p>28 May 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/378">Issue #378</a>: Do not use internal importlib._bootstrap module.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/390">Issue #390</a>: Disallow console scripts with path separators in
the name. Removes unintended functionality and brings behavior
into parity with pip.</li>
</ul>
</div>
<div class="section" id="id480">
<h3>16.0<a class="headerlink" href="#id480" title="Permalink to this headline">¶</a></h3>
<p>18 May 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/130">BB Pull Request #130</a>: Better error messages for errors in
parsed requirements.</li>
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/133">BB Pull Request #133</a>: Removed <code class="docutils literal notranslate"><span class="pre">setuptools.tests</span></code> from the
installed packages.</li>
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/129">BB Pull Request #129</a>: Address deprecation warning due to usage
of imp module.</li>
</ul>
</div>
<div class="section" id="id481">
<h3>15.2<a class="headerlink" href="#id481" title="Permalink to this headline">¶</a></h3>
<p>26 Apr 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/373">Issue #373</a>: Provisionally expose
<code class="docutils literal notranslate"><span class="pre">pkg_resources._initialize_master_working_set</span></code>, allowing for
imperative re-initialization of the master working set.</li>
</ul>
</div>
<div class="section" id="id482">
<h3>15.1<a class="headerlink" href="#id482" title="Permalink to this headline">¶</a></h3>
<p>15 Apr 2015</p>
<ul class="simple">
<li>Updated to <a class="reference external" href="https://github.com/pypa/packaging/blob/15.1/CHANGELOG.rst">Packaging 15.1</a> to address <a class="reference external" href="https://github.com/pypa/packaging/issues/28">Packaging #28</a>.</li>
<li>Fix <code class="docutils literal notranslate"><span class="pre">setuptools.sandbox._execfile()</span></code> with Python 3.1.</li>
</ul>
</div>
<div class="section" id="id483">
<h3>15.0<a class="headerlink" href="#id483" title="Permalink to this headline">¶</a></h3>
<p>03 Apr 2015</p>
<ul>
<li><p class="first"><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/126">BB Pull Request #126</a>: DistributionNotFound message now lists the package or
packages that required it. E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pkg_resources</span><span class="o">.</span><span class="n">DistributionNotFound</span><span class="p">:</span> <span class="n">The</span> <span class="s1">&#39;colorama&gt;=0.3.1&#39;</span> <span class="n">distribution</span> <span class="n">was</span> <span class="ow">not</span> <span class="n">found</span> <span class="ow">and</span> <span class="ow">is</span> <span class="n">required</span> <span class="n">by</span> <span class="n">smlib</span><span class="o">.</span><span class="n">log</span><span class="o">.</span>
</pre></div>
</div>
<p>Note that zc.buildout once dependended on the string rendering of this
message to determine the package that was not found. This expectation
has since been changed, but older versions of buildout may experience
problems. See <a class="reference external" href="https://github.com/buildout/buildout/issues/242">Buildout #242</a> for details.</p>
</li>
</ul>
</div>
<div class="section" id="id484">
<h3>14.3.1<a class="headerlink" href="#id484" title="Permalink to this headline">¶</a></h3>
<p>20 Mar 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/307">Issue #307</a>: Removed <a class="reference external" href="https://www.python.org/dev/peps/pep-0440/">PEP-440</a> warning during parsing of versions
in <code class="docutils literal notranslate"><span class="pre">pkg_resources.Distribution</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/364">Issue #364</a>: Replace deprecated usage with recommended usage of
<code class="docutils literal notranslate"><span class="pre">EntryPoint.load</span></code>.</li>
</ul>
</div>
<div class="section" id="id486">
<h3>14.3<a class="headerlink" href="#id486" title="Permalink to this headline">¶</a></h3>
<p>15 Mar 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/254">Issue #254</a>: When creating temporary egg cache on Unix, use mode 755
for creating the directory to avoid the subsequent warning if
the directory is group writable.</li>
</ul>
</div>
<div class="section" id="id487">
<h3>14.2<a class="headerlink" href="#id487" title="Permalink to this headline">¶</a></h3>
<p>15 Mar 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/137">Issue #137</a>: Update <code class="docutils literal notranslate"><span class="pre">Distribution.hashcmp</span></code> so that Distributions with
None for pyversion or platform can be compared against Distributions
defining those attributes.</li>
</ul>
</div>
<div class="section" id="id488">
<h3>14.1.1<a class="headerlink" href="#id488" title="Permalink to this headline">¶</a></h3>
<p>14 Mar 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/360">Issue #360</a>: Removed undesirable behavior from test runs, preventing
write tests and installation to system site packages.</li>
</ul>
</div>
<div class="section" id="id489">
<h3>14.1<a class="headerlink" href="#id489" title="Permalink to this headline">¶</a></h3>
<p>14 Mar 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/125">BB Pull Request #125</a>: Add <code class="docutils literal notranslate"><span class="pre">__ne__</span></code> to Requirement class.</li>
<li>Various refactoring of easy_install.</li>
</ul>
</div>
<div class="section" id="id490">
<h3>14.0<a class="headerlink" href="#id490" title="Permalink to this headline">¶</a></h3>
<p>06 Mar 2015</p>
<ul class="simple">
<li>Bootstrap script now accepts <code class="docutils literal notranslate"><span class="pre">--to-dir</span></code> to customize save directory or
allow for re-use of existing repository of setuptools versions. See
<a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/112">BB Pull Request #112</a> for background.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/285">Issue #285</a>: <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> no longer will default to installing
packages to the “user site packages” directory if it is itself installed
there. Instead, the user must pass <code class="docutils literal notranslate"><span class="pre">--user</span></code> in all cases to install
packages to the user site packages.
This behavior now matches that of “pip install”. To configure
an environment to always install to the user site packages, consider
using the “install-dir” and “scripts-dir” parameters to easy_install
through an appropriate distutils config file.</li>
</ul>
</div>
<div class="section" id="id491">
<h3>13.0.2<a class="headerlink" href="#id491" title="Permalink to this headline">¶</a></h3>
<p>06 Mar 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/359">Issue #359</a>: Include pytest.ini in the sdist so invocation of py.test on the
sdist honors the pytest configuration.</li>
</ul>
</div>
<div class="section" id="id492">
<h3>13.0.1<a class="headerlink" href="#id492" title="Permalink to this headline">¶</a></h3>
<p>05 Mar 2015</p>
<p>Re-release of 13.0. Intermittent connectivity issues caused the release
process to fail and PyPI uploads no longer accept files for 13.0.</p>
</div>
<div class="section" id="id493">
<h3>13.0<a class="headerlink" href="#id493" title="Permalink to this headline">¶</a></h3>
<p>05 Mar 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/356">Issue #356</a>: Back out <a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/119">BB Pull Request #119</a> as it requires Setuptools 10 or later
as the source during an upgrade.</li>
<li>Removed build_py class from setup.py. According to 892f439d216e, this
functionality was added to support upgrades from old Distribute versions,
0.6.5 and 0.6.6.</li>
</ul>
</div>
<div class="section" id="id494">
<h3>12.4<a class="headerlink" href="#id494" title="Permalink to this headline">¶</a></h3>
<p>04 Mar 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/119">BB Pull Request #119</a>: Restore writing of <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> to metadata
(previously added in 8.4 and removed in 9.0).</li>
</ul>
</div>
<div class="section" id="id496">
<h3>12.3<a class="headerlink" href="#id496" title="Permalink to this headline">¶</a></h3>
<p>26 Feb 2015</p>
<ul class="simple">
<li>Documentation is now linked using the rst.linker package.</li>
<li>Fix <code class="docutils literal notranslate"><span class="pre">setuptools.command.easy_install.extract_wininst_cfg()</span></code>
with Python 2.6 and 2.7.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/354">Issue #354</a>. Added documentation on building setuptools
documentation.</li>
</ul>
</div>
<div class="section" id="id497">
<h3>12.2<a class="headerlink" href="#id497" title="Permalink to this headline">¶</a></h3>
<p>16 Feb 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/345">Issue #345</a>: Unload all modules under pkg_resources during
<code class="docutils literal notranslate"><span class="pre">ez_setup.use_setuptools()</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/336">Issue #336</a>: Removed deprecation from <code class="docutils literal notranslate"><span class="pre">ez_setup.use_setuptools</span></code>,
as it is clearly still used by buildout’s bootstrap. <code class="docutils literal notranslate"><span class="pre">ez_setup</span></code>
remains deprecated for use by individual packages.</li>
<li>Simplified implementation of <code class="docutils literal notranslate"><span class="pre">ez_setup.use_setuptools</span></code>.</li>
</ul>
</div>
<div class="section" id="id498">
<h3>12.1<a class="headerlink" href="#id498" title="Permalink to this headline">¶</a></h3>
<p>10 Feb 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/118">BB Pull Request #118</a>: Soften warning for non-normalized versions in
Distribution.</li>
</ul>
</div>
<div class="section" id="id499">
<h3>12.0.5<a class="headerlink" href="#id499" title="Permalink to this headline">¶</a></h3>
<p>26 Jan 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/339">Issue #339</a>: Correct Attribute reference in <code class="docutils literal notranslate"><span class="pre">cant_write_to_target</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/336">Issue #336</a>: Deprecated <code class="docutils literal notranslate"><span class="pre">ez_setup.use_setuptools</span></code>.</li>
</ul>
</div>
<div class="section" id="id501">
<h3>12.0.4<a class="headerlink" href="#id501" title="Permalink to this headline">¶</a></h3>
<p>20 Jan 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/335">Issue #335</a>: Fix script header generation on Windows.</li>
</ul>
</div>
<div class="section" id="id502">
<h3>12.0.3<a class="headerlink" href="#id502" title="Permalink to this headline">¶</a></h3>
<p>18 Jan 2015</p>
<ul class="simple">
<li>Fixed incorrect class attribute in <code class="docutils literal notranslate"><span class="pre">install_scripts</span></code>. Tests would be nice.</li>
</ul>
</div>
<div class="section" id="id503">
<h3>12.0.2<a class="headerlink" href="#id503" title="Permalink to this headline">¶</a></h3>
<p>18 Jan 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/331">Issue #331</a>: Fixed <code class="docutils literal notranslate"><span class="pre">install_scripts</span></code> command on Windows systems corrupting
the header.</li>
</ul>
</div>
<div class="section" id="id504">
<h3>12.0.1<a class="headerlink" href="#id504" title="Permalink to this headline">¶</a></h3>
<p>16 Jan 2015</p>
<ul class="simple">
<li>Restore <code class="docutils literal notranslate"><span class="pre">setuptools.command.easy_install.sys_executable</span></code> for pbr
compatibility. For the future, tools should construct a CommandSpec
explicitly.</li>
</ul>
</div>
<div class="section" id="id505">
<h3>12.0<a class="headerlink" href="#id505" title="Permalink to this headline">¶</a></h3>
<p>16 Jan 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/188">Issue #188</a>: Setuptools now support multiple entities in the value for
<code class="docutils literal notranslate"><span class="pre">build.executable</span></code>, such that an executable of “/usr/bin/env my-python” may
be specified. This means that systems with a specified executable whose name
has spaces in the path must be updated to escape or quote that value.</li>
<li>Deprecated <code class="docutils literal notranslate"><span class="pre">easy_install.ScriptWriter.get_writer</span></code>, replaced by <code class="docutils literal notranslate"><span class="pre">.best()</span></code>
with slightly different semantics (no force_windows flag).</li>
</ul>
</div>
<div class="section" id="id506">
<h3>11.3.1<a class="headerlink" href="#id506" title="Permalink to this headline">¶</a></h3>
<p>06 Jan 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/327">Issue #327</a>: Formalize and restore support for any printable character in an
entry point name.</li>
</ul>
</div>
<div class="section" id="id507">
<h3>11.3<a class="headerlink" href="#id507" title="Permalink to this headline">¶</a></h3>
<p>05 Jan 2015</p>
<ul>
<li><p class="first">Expose <code class="docutils literal notranslate"><span class="pre">EntryPoint.resolve</span></code> in place of EntryPoint._load, implementing the
simple, non-requiring load. Deprecated all uses of <code class="docutils literal notranslate"><span class="pre">EntryPoint._load</span></code>
except for calling with no parameters, which is just a shortcut for
<code class="docutils literal notranslate"><span class="pre">ep.require();</span> <span class="pre">ep.resolve();</span></code>.</p>
<p>Apps currently invoking <code class="docutils literal notranslate"><span class="pre">ep.load(require=False)</span></code> should instead do the
following if wanting to avoid the deprecating warning:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">getattr</span><span class="p">(</span><span class="n">ep</span><span class="p">,</span> <span class="s2">&quot;resolve&quot;</span><span class="p">,</span> <span class="k">lambda</span><span class="p">:</span> <span class="n">ep</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">require</span><span class="o">=</span><span class="kc">False</span><span class="p">))()</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="id508">
<h3>11.2<a class="headerlink" href="#id508" title="Permalink to this headline">¶</a></h3>
<p>05 Jan 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/pip/issues/2326">Pip #2326</a>: Report deprecation warning at stacklevel 2 for easier diagnosis.</li>
</ul>
</div>
<div class="section" id="id509">
<h3>11.1<a class="headerlink" href="#id509" title="Permalink to this headline">¶</a></h3>
<p>04 Jan 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/281">Issue #281</a>: Since Setuptools 6.1 (<a class="reference external" href="https://github.com/pypa/setuptools/issues/268">Issue #268</a>), a ValueError would be raised
in certain cases where VersionConflict was raised with two arguments, which
occurred in <code class="docutils literal notranslate"><span class="pre">pkg_resources.WorkingSet.find</span></code>. This release adds support
for indicating the dependent packages while maintaining support for
a VersionConflict when no dependent package context is known. New unit tests
now capture the expected interface.</li>
</ul>
</div>
<div class="section" id="id510">
<h3>11.0<a class="headerlink" href="#id510" title="Permalink to this headline">¶</a></h3>
<p>02 Jan 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/interoperability-peps/issues/3">Interop #3</a>: Upgrade to <a class="reference external" href="https://github.com/pypa/packaging/blob/15.0/CHANGELOG.rst">Packaging 15.0</a>; updates to <a class="reference external" href="https://www.python.org/dev/peps/pep-0440/">PEP 440</a> so that &gt;1.7 does
not exclude 1.7.1 but does exclude 1.7.0 and 1.7.0.post1.</li>
</ul>
</div>
<div class="section" id="id512">
<h3>10.2.1<a class="headerlink" href="#id512" title="Permalink to this headline">¶</a></h3>
<p>02 Jan 2015</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/323">Issue #323</a>: Fix regression in entry point name parsing.</li>
</ul>
</div>
<div class="section" id="id513">
<h3>10.2<a class="headerlink" href="#id513" title="Permalink to this headline">¶</a></h3>
<p>02 Jan 2015</p>
<ul class="simple">
<li>Deprecated use of EntryPoint.load(require=False). Passing a boolean to a
function to select behavior is an anti-pattern. Instead use
<code class="docutils literal notranslate"><span class="pre">Entrypoint._load()</span></code>.</li>
<li>Substantial refactoring of all unit tests. Tests are now much leaner and
re-use a lot of fixtures and contexts for better clarity of purpose.</li>
</ul>
</div>
<div class="section" id="id514">
<h3>10.1<a class="headerlink" href="#id514" title="Permalink to this headline">¶</a></h3>
<p>31 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/320">Issue #320</a>: Added a compatibility implementation of
<code class="docutils literal notranslate"><span class="pre">sdist._default_revctrl</span></code>
so that systems relying on that interface do not fail (namely, Ubuntu 12.04
and similar Debian releases).</li>
</ul>
</div>
<div class="section" id="id515">
<h3>10.0.1<a class="headerlink" href="#id515" title="Permalink to this headline">¶</a></h3>
<p>30 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/319">Issue #319</a>: Fixed issue installing pure distutils packages.</li>
</ul>
</div>
<div class="section" id="id516">
<h3>10.0<a class="headerlink" href="#id516" title="Permalink to this headline">¶</a></h3>
<p>30 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/313">Issue #313</a>: Removed built-in support for subversion. Projects wishing to
retain support for subversion will need to use a third party library. The
extant implementation is being ported to <a class="reference external" href="https://pypi.org/project/setuptools_svn/">setuptools_svn</a>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/315">Issue #315</a>: Updated setuptools to hide its own loaded modules during
installation of another package. This change will enable setuptools to
upgrade (or downgrade) itself even when its own metadata and implementation
change.</li>
</ul>
</div>
<div class="section" id="id517">
<h3>9.1<a class="headerlink" href="#id517" title="Permalink to this headline">¶</a></h3>
<p>29 Dec 2014</p>
<ul class="simple">
<li>Prefer vendored packaging library <a class="reference external" href="https://github.com/pypa/setuptools/commit/170657b68f4b92e7e1bf82f5e19a831f5744af67">as recommended</a>.</li>
</ul>
</div>
<div class="section" id="id518">
<h3>9.0.1<a class="headerlink" href="#id518" title="Permalink to this headline">¶</a></h3>
<p>29 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/312">Issue #312</a>: Restored presence of pkg_resources API tests (doctest) to sdist.</li>
</ul>
</div>
<div class="section" id="id519">
<h3>9.0<a class="headerlink" href="#id519" title="Permalink to this headline">¶</a></h3>
<p>28 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/314">Issue #314</a>: Disabled support for <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> metadata to avoid issue
where Setuptools was unable to upgrade over earlier versions.</li>
</ul>
</div>
<div class="section" id="id520">
<h3>8.4<a class="headerlink" href="#id520" title="Permalink to this headline">¶</a></h3>
<p>26 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/106">BB Pull Request #106</a>: Now write <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> metadata.</li>
</ul>
</div>
<div class="section" id="id521">
<h3>8.3<a class="headerlink" href="#id521" title="Permalink to this headline">¶</a></h3>
<p>24 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/311">Issue #311</a>: Decoupled pkg_resources from setuptools once again.
<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> is now a package instead of a module.</li>
</ul>
</div>
<div class="section" id="id522">
<h3>8.2.1<a class="headerlink" href="#id522" title="Permalink to this headline">¶</a></h3>
<p>18 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/306">Issue #306</a>: Suppress warnings about Version format except in select scenarios
(such as installation).</li>
</ul>
</div>
<div class="section" id="id523">
<h3>8.2<a class="headerlink" href="#id523" title="Permalink to this headline">¶</a></h3>
<p>18 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/85">BB Pull Request #85</a>: Search egg-base when adding egg-info to manifest.</li>
</ul>
</div>
<div class="section" id="id524">
<h3>8.1<a class="headerlink" href="#id524" title="Permalink to this headline">¶</a></h3>
<p>18 Dec 2014</p>
<ul class="simple">
<li>Upgrade <code class="docutils literal notranslate"><span class="pre">packaging</span></code> to 14.5, giving preference to “rc” as designator for
release candidates over “c”.</li>
<li><a class="reference external" href="https://www.python.org/dev/peps/pep-0440/">PEP-440</a> warnings are now raised as their own class,
<code class="docutils literal notranslate"><span class="pre">pkg_resources.PEP440Warning</span></code>, instead of RuntimeWarning.</li>
<li>Disabled warnings on empty versions.</li>
</ul>
</div>
<div class="section" id="id526">
<h3>8.0.4<a class="headerlink" href="#id526" title="Permalink to this headline">¶</a></h3>
<p>15 Dec 2014</p>
<ul class="simple">
<li>Upgrade <code class="docutils literal notranslate"><span class="pre">packaging</span></code> to 14.4, fixing an error where there is a
different result for if 2.0.5 is contained within &gt;2.0dev and &gt;2.0.dev even
though normalization rules should have made them equal.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/296">Issue #296</a>: Add warning when a version is parsed as legacy. This warning will
make it easier for developers to recognize deprecated version numbers.</li>
</ul>
</div>
<div class="section" id="id527">
<h3>8.0.3<a class="headerlink" href="#id527" title="Permalink to this headline">¶</a></h3>
<p>15 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/296">Issue #296</a>: Restored support for <code class="docutils literal notranslate"><span class="pre">__hash__</span></code> on parse_version results.</li>
</ul>
</div>
<div class="section" id="id529">
<h3>8.0.2<a class="headerlink" href="#id529" title="Permalink to this headline">¶</a></h3>
<p>14 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/296">Issue #296</a>: Restored support for <code class="docutils literal notranslate"><span class="pre">__getitem__</span></code> and sort operations on
parse_version result.</li>
</ul>
</div>
<div class="section" id="id531">
<h3>8.0.1<a class="headerlink" href="#id531" title="Permalink to this headline">¶</a></h3>
<p>13 Dec 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/296">Issue #296</a>: Restore support for iteration over parse_version result, but
deprecated that usage with a warning. Fixes failure with buildout.</li>
</ul>
</div>
<div class="section" id="id533">
<h3>8.0<a class="headerlink" href="#id533" title="Permalink to this headline">¶</a></h3>
<p>13 Dec 2014</p>
<ul class="simple">
<li>Implement <a class="reference external" href="https://www.python.org/dev/peps/pep-0440/">PEP 440</a> within
pkg_resources and setuptools. This change
deprecates some version numbers such that they will no longer be installable
without using the <code class="docutils literal notranslate"><span class="pre">===</span></code> escape hatch. See <a class="reference external" href="https://bitbucket.org/pypa/setuptools/commits/dcd552da643c4448056de84c73d56da6d70769d5#chg-setuptools/tests/test_resources.py">the changes to test_resources</a>
for specific examples of version numbers and specifiers that are no longer
supported. Setuptools now “vendors” the <a class="reference external" href="https://github.com/pypa/packaging">packaging</a> library.</li>
</ul>
</div>
<div class="section" id="id535">
<h3>7.0<a class="headerlink" href="#id535" title="Permalink to this headline">¶</a></h3>
<p>19 Oct 2014</p>
<ul>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/80">Issue #80</a>, <a class="reference external" href="https://github.com/pypa/setuptools/issues/209">Issue #209</a>: Eggs that are downloaded for <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code>,
<code class="docutils literal notranslate"><span class="pre">test_requires</span></code>, etc. are now placed in a <code class="docutils literal notranslate"><span class="pre">./.eggs</span></code> directory instead of
directly in the current directory. This choice of location means the files
can be readily managed (removed, ignored). Additionally,
later phases or invocations of setuptools will not detect the package as
already installed and ignore it for permanent install (See <a class="reference external" href="https://github.com/pypa/setuptools/issues/209">#209</a>).</p>
<p>This change is indicated as backward-incompatible as installations that
depend on the installation in the current directory will need to account for
the new location. Systems that ignore <code class="docutils literal notranslate"><span class="pre">*.egg</span></code> will probably need to be
adapted to ignore <code class="docutils literal notranslate"><span class="pre">.eggs</span></code>. The files will need to be manually moved or
will be retrieved again. Most use cases will require no attention.</p>
</li>
</ul>
</div>
<div class="section" id="id537">
<h3>6.1<a class="headerlink" href="#id537" title="Permalink to this headline">¶</a></h3>
<p>11 Oct 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/268">Issue #268</a>: When resolving package versions, a VersionConflict now reports
which package previously required the conflicting version.</li>
</ul>
</div>
<div class="section" id="id539">
<h3>6.0.2<a class="headerlink" href="#id539" title="Permalink to this headline">¶</a></h3>
<p>29 Sep 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/262">Issue #262</a>: Fixed regression in pip install due to egg-info directories
being omitted. Re-opens <a class="reference external" href="https://github.com/pypa/setuptools/issues/118">Issue #118</a>.</li>
</ul>
</div>
<div class="section" id="id541">
<h3>6.0.1<a class="headerlink" href="#id541" title="Permalink to this headline">¶</a></h3>
<p>27 Sep 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/259">Issue #259</a>: Fixed regression with namespace package handling on <code class="docutils literal notranslate"><span class="pre">single</span>
<span class="pre">version,</span> <span class="pre">externally</span> <span class="pre">managed</span></code> installs.</li>
</ul>
</div>
<div class="section" id="id542">
<h3>6.0<a class="headerlink" href="#id542" title="Permalink to this headline">¶</a></h3>
<p>27 Sep 2014</p>
<ul>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/100">Issue #100</a>: When building a distribution, Setuptools will no longer match
default files using platform-dependent case sensitivity, but rather will
only match the files if their case matches exactly. As a result, on Windows
and other case-insensitive file systems, files with names such as
‘readme.txt’ or ‘README.TXT’ will be omitted from the distribution and a
warning will be issued indicating that ‘README.txt’ was not found. Other
filenames affected are:</p>
<blockquote>
<div><ul class="simple">
<li>README.rst</li>
<li>README</li>
<li>setup.cfg</li>
<li>setup.py (or the script name)</li>
<li>test/test*.py</li>
</ul>
</div></blockquote>
<p>Any users producing distributions with filenames that match those above
case-insensitively, but not case-sensitively, should rename those files in
their repository for better portability.</p>
</li>
<li><p class="first"><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/72">BB Pull Request #72</a>: When using <code class="docutils literal notranslate"><span class="pre">single_version_externally_managed</span></code>, the
exclusion list now includes Python 3.2 <code class="docutils literal notranslate"><span class="pre">__pycache__</span></code> entries.</p>
</li>
<li><p class="first"><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/76">BB Pull Request #76</a> and <a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/78">BB Pull Request #78</a>: lines in top_level.txt are now
ordered deterministically.</p>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/118">Issue #118</a>: The egg-info directory is now no longer included in the list
of outputs.</p>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/258">Issue #258</a>: Setuptools now patches distutils msvc9compiler to
recognize the specially-packaged compiler package for easy extension module
support on Python 2.6, 2.7, and 3.2.</p>
</li>
</ul>
</div>
<div class="section" id="id544">
<h3>5.8<a class="headerlink" href="#id544" title="Permalink to this headline">¶</a></h3>
<p>18 Sep 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/237">Issue #237</a>: <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> now uses explicit detection of Python 2 vs.
Python 3, supporting environments where builtins have been patched to make
Python 3 look more like Python 2.</li>
</ul>
</div>
<div class="section" id="id545">
<h3>5.7<a class="headerlink" href="#id545" title="Permalink to this headline">¶</a></h3>
<p>15 Aug 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/240">Issue #240</a>: Based on real-world performance measures against 5.4, zip
manifests are now cached in all circumstances. The
<code class="docutils literal notranslate"><span class="pre">PKG_RESOURCES_CACHE_ZIP_MANIFESTS</span></code> environment variable is no longer
relevant. The observed “memory increase” referenced in the 5.4 release
notes and detailed in <a class="reference external" href="https://github.com/pypa/setuptools/issues/154">Issue #154</a> was likely not an increase over the status
quo, but rather only an increase over not storing the zip info at all.</li>
</ul>
</div>
<div class="section" id="id546">
<h3>5.6<a class="headerlink" href="#id546" title="Permalink to this headline">¶</a></h3>
<p>14 Aug 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/242">Issue #242</a>: Use absolute imports in svn_utils to avoid issues if the
installing package adds an xml module to the path.</li>
</ul>
</div>
<div class="section" id="id547">
<h3>5.5.1<a class="headerlink" href="#id547" title="Permalink to this headline">¶</a></h3>
<p>10 Aug 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/239">Issue #239</a>: Fix typo in 5.5 such that fix did not take.</li>
</ul>
</div>
<div class="section" id="id548">
<h3>5.5<a class="headerlink" href="#id548" title="Permalink to this headline">¶</a></h3>
<p>10 Aug 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/239">Issue #239</a>: Setuptools now includes the setup_requires directive on
Distribution objects and validates the syntax just like install_requires
and tests_require directives.</li>
</ul>
</div>
<div class="section" id="id550">
<h3>5.4.2<a class="headerlink" href="#id550" title="Permalink to this headline">¶</a></h3>
<p>01 Aug 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/236">Issue #236</a>: Corrected regression in execfile implementation for Python 2.6.</li>
</ul>
</div>
<div class="section" id="id551">
<h3>5.4.1<a class="headerlink" href="#id551" title="Permalink to this headline">¶</a></h3>
<p>06 Jul 2014</p>
<ul class="simple">
<li><a class="reference external" href="http://bugs.python.org/issue7776">Python #7776</a>: (ssl_support) Correct usage of host for validation when
tunneling for HTTPS.</li>
</ul>
</div>
<div class="section" id="id552">
<h3>5.4<a class="headerlink" href="#id552" title="Permalink to this headline">¶</a></h3>
<p>05 Jul 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/154">Issue #154</a>: <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> will now cache the zip manifests rather than
re-processing the same file from disk multiple times, but only if the
environment variable <code class="docutils literal notranslate"><span class="pre">PKG_RESOURCES_CACHE_ZIP_MANIFESTS</span></code> is set. Clients
that package many modules in the same zip file will see some improvement
in startup time by enabling this feature. This feature is not enabled by
default because it causes a substantial increase in memory usage.</li>
</ul>
</div>
<div class="section" id="id554">
<h3>5.3<a class="headerlink" href="#id554" title="Permalink to this headline">¶</a></h3>
<p>28 Jun 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/185">Issue #185</a>: Make svn tagging work on the new style SVN metadata.
Thanks cazabon!</li>
<li>Prune revision control directories (e.g .svn) from base path
as well as sub-directories.</li>
</ul>
</div>
<div class="section" id="id555">
<h3>5.2<a class="headerlink" href="#id555" title="Permalink to this headline">¶</a></h3>
<p>22 Jun 2014</p>
<ul class="simple">
<li>Added a <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/developer-guide.html">Developer Guide</a> to the official
documentation.</li>
<li>Some code refactoring and cleanup was done with no intended behavioral
changes.</li>
<li>During install_egg_info, the generated lines for namespace package .pth
files are now processed even during a dry run.</li>
</ul>
</div>
<div class="section" id="id556">
<h3>5.1<a class="headerlink" href="#id556" title="Permalink to this headline">¶</a></h3>
<p>15 Jun 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/202">Issue #202</a>: Implemented more robust cache invalidation for the ZipImporter,
building on the work in <a class="reference external" href="https://github.com/pypa/setuptools/issues/168">Issue #168</a>. Special thanks to Jurko Gospodnetic and
PJE.</li>
</ul>
</div>
<div class="section" id="id557">
<h3>5.0.2<a class="headerlink" href="#id557" title="Permalink to this headline">¶</a></h3>
<p>15 Jun 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/220">Issue #220</a>: Restored script templates.</li>
</ul>
</div>
<div class="section" id="id558">
<h3>5.0.1<a class="headerlink" href="#id558" title="Permalink to this headline">¶</a></h3>
<p>14 Jun 2014</p>
<ul class="simple">
<li>Renamed script templates to end with .tmpl now that they no longer need
to be processed by 2to3. Fixes spurious syntax errors during build/install.</li>
</ul>
</div>
<div class="section" id="id559">
<h3>5.0<a class="headerlink" href="#id559" title="Permalink to this headline">¶</a></h3>
<p>14 Jun 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/218">Issue #218</a>: Re-release of 3.8.1 to signal that it supersedes 4.x.</li>
<li>Incidentally, script templates were updated not to include the triple-quote
escaping.</li>
</ul>
</div>
<div class="section" id="and-3-8-1-and-4-0-1">
<h3>3.7.1 and 3.8.1 and 4.0.1<a class="headerlink" href="#and-3-8-1-and-4-0-1" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/213">Issue #213</a>: Use legacy StringIO behavior for compatibility under pbr.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/218">Issue #218</a>: Setuptools 3.8.1 superseded 4.0.1, and 4.x was removed
from the available versions to install.</li>
</ul>
</div>
<div class="section" id="id561">
<h3>4.0<a class="headerlink" href="#id561" title="Permalink to this headline">¶</a></h3>
<p>01 Jun 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/210">Issue #210</a>: <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code> now copies scripts in binary mode rather
than text mode, matching the behavior of the <code class="docutils literal notranslate"><span class="pre">install</span></code> command.</li>
</ul>
</div>
<div class="section" id="id562">
<h3>3.8<a class="headerlink" href="#id562" title="Permalink to this headline">¶</a></h3>
<p>01 Jun 2014</p>
<ul class="simple">
<li>Extend <a class="reference external" href="https://github.com/pypa/setuptools/issues/197">Issue #197</a> workaround to include all Python 3 versions prior to
3.2.2.</li>
</ul>
</div>
<div class="section" id="id563">
<h3>3.7<a class="headerlink" href="#id563" title="Permalink to this headline">¶</a></h3>
<p>28 May 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/193">Issue #193</a>: Improved handling of Unicode filenames when building manifests.</li>
</ul>
</div>
<div class="section" id="id564">
<h3>3.6<a class="headerlink" href="#id564" title="Permalink to this headline">¶</a></h3>
<p>07 May 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/203">Issue #203</a>: Honor proxy settings for Powershell downloader in the bootstrap
routine.</li>
</ul>
</div>
<div class="section" id="id565">
<h3>3.5.2<a class="headerlink" href="#id565" title="Permalink to this headline">¶</a></h3>
<p>07 May 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/168">Issue #168</a>: More robust handling of replaced zip files and stale caches.
Fixes ZipImportError complaining about a ‘bad local header’.</li>
</ul>
</div>
<div class="section" id="id567">
<h3>3.5.1<a class="headerlink" href="#id567" title="Permalink to this headline">¶</a></h3>
<p>04 May 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/199">Issue #199</a>: Restored <code class="docutils literal notranslate"><span class="pre">install._install</span></code> for compatibility with earlier
NumPy versions.</li>
</ul>
</div>
<div class="section" id="id568">
<h3>3.5<a class="headerlink" href="#id568" title="Permalink to this headline">¶</a></h3>
<p>03 May 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/195">Issue #195</a>: Follow symbolic links in find_packages (restoring behavior
broken in 3.4).</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/197">Issue #197</a>: On Python 3.1, PKG-INFO is now saved in a UTF-8 encoding instead
of <code class="docutils literal notranslate"><span class="pre">sys.getpreferredencoding</span></code> to match the behavior on Python 2.6-3.4.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/192">Issue #192</a>: Preferred bootstrap location is now
<a class="reference external" href="https://bootstrap.pypa.io/ez_setup.py">https://bootstrap.pypa.io/ez_setup.py</a> (mirrored from former location).</li>
</ul>
</div>
<div class="section" id="id570">
<h3>3.4.4<a class="headerlink" href="#id570" title="Permalink to this headline">¶</a></h3>
<p>11 Apr 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/184">Issue #184</a>: Correct failure where find_package over-matched packages
when directory traversal isn’t short-circuited.</li>
</ul>
</div>
<div class="section" id="id571">
<h3>3.4.3<a class="headerlink" href="#id571" title="Permalink to this headline">¶</a></h3>
<p>07 Apr 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/183">Issue #183</a>: Really fix test command with Python 3.1.</li>
</ul>
</div>
<div class="section" id="id572">
<h3>3.4.2<a class="headerlink" href="#id572" title="Permalink to this headline">¶</a></h3>
<p>06 Apr 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/183">Issue #183</a>: Fix additional regression in test command on Python 3.1.</li>
</ul>
</div>
<div class="section" id="id574">
<h3>3.4.1<a class="headerlink" href="#id574" title="Permalink to this headline">¶</a></h3>
<p>30 Mar 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/180">Issue #180</a>: Fix regression in test command not caught by py.test-run tests.</li>
</ul>
</div>
<div class="section" id="id575">
<h3>3.4<a class="headerlink" href="#id575" title="Permalink to this headline">¶</a></h3>
<p>30 Mar 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/176">Issue #176</a>: Add parameter to the test command to support a custom test
runner: –test-runner or -r.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/177">Issue #177</a>: Now assume most common invocation to install command on
platforms/environments without stack support (issuing a warning). Setuptools
now installs naturally on IronPython. Behavior on CPython should be
unchanged.</li>
</ul>
</div>
<div class="section" id="id576">
<h3>3.3<a class="headerlink" href="#id576" title="Permalink to this headline">¶</a></h3>
<p>16 Mar 2014</p>
<ul class="simple">
<li>Add <code class="docutils literal notranslate"><span class="pre">include</span></code> parameter to <code class="docutils literal notranslate"><span class="pre">setuptools.find_packages()</span></code>.</li>
</ul>
</div>
<div class="section" id="id577">
<h3>3.2<a class="headerlink" href="#id577" title="Permalink to this headline">¶</a></h3>
<p>14 Mar 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/39">BB Pull Request #39</a>: Add support for C++ targets from Cython <code class="docutils literal notranslate"><span class="pre">.pyx</span></code> files.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/162">Issue #162</a>: Update dependency on certifi to 1.0.1.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/164">Issue #164</a>: Update dependency on wincertstore to 0.2.</li>
</ul>
</div>
<div class="section" id="id578">
<h3>3.1<a class="headerlink" href="#id578" title="Permalink to this headline">¶</a></h3>
<p>08 Mar 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/161">Issue #161</a>: Restore Features functionality to allow backward compatibility
(for Features) until the uses of that functionality is sufficiently removed.</li>
</ul>
</div>
<div class="section" id="id579">
<h3>3.0.2<a class="headerlink" href="#id579" title="Permalink to this headline">¶</a></h3>
<p>06 Mar 2014</p>
<ul class="simple">
<li>Correct typo in previous bugfix.</li>
</ul>
</div>
<div class="section" id="id580">
<h3>3.0.1<a class="headerlink" href="#id580" title="Permalink to this headline">¶</a></h3>
<p>06 Mar 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/157">Issue #157</a>: Restore support for Python 2.6 in bootstrap script where
<code class="docutils literal notranslate"><span class="pre">zipfile.ZipFile</span></code> does not yet have support for context managers.</li>
</ul>
</div>
<div class="section" id="id581">
<h3>3.0<a class="headerlink" href="#id581" title="Permalink to this headline">¶</a></h3>
<p>04 Mar 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/125">Issue #125</a>: Prevent Subversion support from creating a ~/.subversion
directory just for checking the presence of a Subversion repository.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/12">Issue #12</a>: Namespace packages are now imported lazily. That is, the mere
declaration of a namespace package in an egg on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> no longer
causes it to be imported when <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> is imported. Note that this
change means that all of a namespace package’s <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files must
include a <code class="docutils literal notranslate"><span class="pre">declare_namespace()</span></code> call in order to ensure that they will be
handled properly at runtime. In 2.x it was possible to get away without
including the declaration, but only at the cost of forcing namespace
packages to be imported early, which 3.0 no longer does.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/148">Issue #148</a>: When building (bdist_egg), setuptools no longer adds
<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files to namespace packages. Any packages that rely on this
behavior will need to create <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files and include the
<code class="docutils literal notranslate"><span class="pre">declare_namespace()</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/7">Issue #7</a>: Setuptools itself is now distributed as a zip archive in addition to
tar archive. ez_setup.py now uses zip archive. This approach avoids the potential
security vulnerabilities presented by use of tar archives in ez_setup.py.
It also leverages the security features added to ZipFile.extract in Python 2.7.4.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/65">Issue #65</a>: Removed deprecated Features functionality.</li>
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/28">BB Pull Request #28</a>: Remove backport of <code class="docutils literal notranslate"><span class="pre">_bytecode_filenames</span></code> which is
available in Python 2.6 and later, but also has better compatibility with
Python 3 environments.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/156">Issue #156</a>: Fix spelling of __PYVENV_LAUNCHER__ variable.</li>
</ul>
</div>
<div class="section" id="id582">
<h3>2.2<a class="headerlink" href="#id582" title="Permalink to this headline">¶</a></h3>
<p>07 Feb 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/141">Issue #141</a>: Restored fix for allowing setup_requires dependencies to
override installed dependencies during setup.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/128">Issue #128</a>: Fixed issue where only the first dependency link was honored
in a distribution where multiple dependency links were supplied.</li>
</ul>
</div>
<div class="section" id="id584">
<h3>2.1.2<a class="headerlink" href="#id584" title="Permalink to this headline">¶</a></h3>
<p>05 Feb 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/144">Issue #144</a>: Read long_description using codecs module to avoid errors
installing on systems where LANG=C.</li>
</ul>
</div>
<div class="section" id="id585">
<h3>2.1.1<a class="headerlink" href="#id585" title="Permalink to this headline">¶</a></h3>
<p>05 Feb 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/139">Issue #139</a>: Fix regression in re_finder for CVS repos (and maybe Git repos
as well).</li>
</ul>
</div>
<div class="section" id="id587">
<h3>2.1<a class="headerlink" href="#id587" title="Permalink to this headline">¶</a></h3>
<p>07 Jan 2014</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/129">Issue #129</a>: Suppress inspection of <code class="docutils literal notranslate"><span class="pre">*.whl</span></code> files when searching for files
in a zip-imported file.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/131">Issue #131</a>: Fix RuntimeError when constructing an egg fetcher.</li>
</ul>
</div>
<div class="section" id="id588">
<h3>2.0.2<a class="headerlink" href="#id588" title="Permalink to this headline">¶</a></h3>
<p>29 Dec 2013</p>
<ul class="simple">
<li>Fix NameError during installation with Python implementations (e.g. Jython)
not containing parser module.</li>
<li>Fix NameError in <code class="docutils literal notranslate"><span class="pre">sdist:re_finder</span></code>.</li>
</ul>
</div>
<div class="section" id="id589">
<h3>2.0.1<a class="headerlink" href="#id589" title="Permalink to this headline">¶</a></h3>
<p>15 Dec 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/124">Issue #124</a>: Fixed error in list detection in upload_docs.</li>
</ul>
</div>
<div class="section" id="id590">
<h3>2.0<a class="headerlink" href="#id590" title="Permalink to this headline">¶</a></h3>
<p>07 Dec 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/121">Issue #121</a>: Exempt lib2to3 pickled grammars from DirectorySandbox.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/41">Issue #41</a>: Dropped support for Python 2.4 and Python 2.5. Clients requiring
setuptools for those versions of Python should use setuptools 1.x.</li>
<li>Removed <code class="docutils literal notranslate"><span class="pre">setuptools.command.easy_install.HAS_USER_SITE</span></code>. Clients
expecting this boolean variable should use <code class="docutils literal notranslate"><span class="pre">site.ENABLE_USER_SITE</span></code>
instead.</li>
<li>Removed <code class="docutils literal notranslate"><span class="pre">pkg_resources.ImpWrapper</span></code>. Clients that expected this class
should use <code class="docutils literal notranslate"><span class="pre">pkgutil.ImpImporter</span></code> instead.</li>
</ul>
</div>
<div class="section" id="id591">
<h3>1.4.2<a class="headerlink" href="#id591" title="Permalink to this headline">¶</a></h3>
<p>01 Dec 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/116">Issue #116</a>: Correct TypeError when reading a local package index on Python
3.</li>
</ul>
</div>
<div class="section" id="id592">
<h3>1.4.1<a class="headerlink" href="#id592" title="Permalink to this headline">¶</a></h3>
<p>23 Nov 2013</p>
<ul>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/114">Issue #114</a>: Use <code class="docutils literal notranslate"><span class="pre">sys.getfilesystemencoding</span></code> for decoding config in
<code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code> distributions.</p>
</li>
<li><p class="first"><a class="reference external" href="https://github.com/pypa/setuptools/issues/105">Issue #105</a> and <a class="reference external" href="https://github.com/pypa/setuptools/issues/113">Issue #113</a>: Establish a more robust technique for
determining the terminal encoding:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>1. Try ``getpreferredencoding``
2. If that returns US_ASCII or None, try the encoding from
   ``getdefaultlocale``. If that encoding was a &quot;fallback&quot; because Python
   could not figure it out from the environment or OS, encoding remains
   unresolved.
3. If the encoding is resolved, then make sure Python actually implements
   the encoding.
4. On the event of an error or unknown codec, revert to fallbacks
   (UTF-8 on Darwin, ASCII on everything else).
5. On the encoding is &#39;mac-roman&#39; on Darwin, use UTF-8 as &#39;mac-roman&#39; was
   a bug on older Python releases.

On a side note, it would seem that the encoding only matters for when SVN
does not yet support ``--xml`` and when getting repository and svn version
numbers. The ``--xml`` technique should yield UTF-8 according to some
messages on the SVN mailing lists. So if the version numbers are always
7-bit ASCII clean, it may be best to only support the file parsing methods
for legacy SVN releases and support for SVN without the subprocess command
would simple go away as support for the older SVNs does.
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="id593">
<h3>1.4<a class="headerlink" href="#id593" title="Permalink to this headline">¶</a></h3>
<p>17 Nov 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/27">Issue #27</a>: <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> will now use credentials from .pypirc if
present for connecting to the package index.</li>
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/21">BB Pull Request #21</a>: Omit unwanted newlines in <code class="docutils literal notranslate"><span class="pre">package_index._encode_auth</span></code>
when the username/password pair length indicates wrapping.</li>
</ul>
</div>
<div class="section" id="id594">
<h3>1.3.2<a class="headerlink" href="#id594" title="Permalink to this headline">¶</a></h3>
<p>09 Nov 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/99">Issue #99</a>: Fix filename encoding issues in SVN support.</li>
</ul>
</div>
<div class="section" id="id595">
<h3>1.3.1<a class="headerlink" href="#id595" title="Permalink to this headline">¶</a></h3>
<p>07 Nov 2013</p>
<ul class="simple">
<li>Remove exuberant warning in SVN support when SVN is not used.</li>
</ul>
</div>
<div class="section" id="id596">
<h3>1.3<a class="headerlink" href="#id596" title="Permalink to this headline">¶</a></h3>
<p>03 Nov 2013</p>
<ul class="simple">
<li>Address security vulnerability in SSL match_hostname check as reported in
<a class="reference external" href="http://bugs.python.org/issue17997">Python #17997</a>.</li>
<li>Prefer <a class="reference external" href="https://pypi.org/project/backports.ssl_match_hostname/">backports.ssl_match_hostname</a> for backport
implementation if present.</li>
<li>Correct NameError in <code class="docutils literal notranslate"><span class="pre">ssl_support</span></code> module (<code class="docutils literal notranslate"><span class="pre">socket.error</span></code>).</li>
</ul>
</div>
<div class="section" id="id597">
<h3>1.2<a class="headerlink" href="#id597" title="Permalink to this headline">¶</a></h3>
<p>02 Nov 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/26">Issue #26</a>: Add support for SVN 1.7. Special thanks to Philip Thiem for the
contribution.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/93">Issue #93</a>: Wheels are now distributed with every release. Note that as
reported in <a class="reference external" href="https://github.com/pypa/setuptools/issues/108">Issue #108</a>, as of Pip 1.4, scripts aren’t installed properly
from wheels. Therefore, if using Pip to install setuptools from a wheel,
the <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> command will not be available.</li>
<li>Setuptools “natural” launcher support, introduced in 1.0, is now officially
supported.</li>
</ul>
</div>
<div class="section" id="id598">
<h3>1.1.7<a class="headerlink" href="#id598" title="Permalink to this headline">¶</a></h3>
<p>11 Apr 2013</p>
<ul class="simple">
<li>Fixed behavior of NameError handling in ‘script template (dev).py’ (script
launcher for ‘develop’ installs).</li>
<li><code class="docutils literal notranslate"><span class="pre">ez_setup.py</span></code> now ensures partial downloads are cleaned up following
a failed download.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/363">Distribute #363</a> and <a class="reference external" href="https://github.com/pypa/setuptools/issues/55">Issue #55</a>: Skip an sdist test that fails on locales
other than UTF-8.</li>
</ul>
</div>
<div class="section" id="id599">
<h3>1.1.6<a class="headerlink" href="#id599" title="Permalink to this headline">¶</a></h3>
<p>18 Sep 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/349">Distribute #349</a>: <code class="docutils literal notranslate"><span class="pre">sandbox.execfile</span></code> now opens the target file in binary
mode, thus honoring a BOM in the file when compiled.</li>
</ul>
</div>
<div class="section" id="id600">
<h3>1.1.5<a class="headerlink" href="#id600" title="Permalink to this headline">¶</a></h3>
<p>12 Sep 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/69">Issue #69</a>: Second attempt at fix (logic was reversed).</li>
</ul>
</div>
<div class="section" id="id601">
<h3>1.1.4<a class="headerlink" href="#id601" title="Permalink to this headline">¶</a></h3>
<p>07 Sep 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/77">Issue #77</a>: Fix error in upload command (Python 2.4).</li>
</ul>
</div>
<div class="section" id="id602">
<h3>1.1.3<a class="headerlink" href="#id602" title="Permalink to this headline">¶</a></h3>
<p>06 Sep 2013</p>
<ul class="simple">
<li>Fix NameError in previous patch.</li>
</ul>
</div>
<div class="section" id="id603">
<h3>1.1.2<a class="headerlink" href="#id603" title="Permalink to this headline">¶</a></h3>
<p>06 Sep 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/69">Issue #69</a>: Correct issue where 404 errors are returned for URLs with
fragments in them (such as #egg=).</li>
</ul>
</div>
<div class="section" id="id605">
<h3>1.1.1<a class="headerlink" href="#id605" title="Permalink to this headline">¶</a></h3>
<p>03 Sep 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/75">Issue #75</a>: Add <code class="docutils literal notranslate"><span class="pre">--insecure</span></code> option to ez_setup.py to accommodate
environments where a trusted SSL connection cannot be validated.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/76">Issue #76</a>: Fix AttributeError in upload command with Python 2.4.</li>
</ul>
</div>
<div class="section" id="id606">
<h3>1.1<a class="headerlink" href="#id606" title="Permalink to this headline">¶</a></h3>
<p>26 Aug 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/71">Issue #71</a> (<a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/333">Distribute #333</a>): EasyInstall now puts less emphasis on the
condition when a host is blocked via <code class="docutils literal notranslate"><span class="pre">--allow-hosts</span></code>.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/72">Issue #72</a>: Restored Python 2.4 compatibility in <code class="docutils literal notranslate"><span class="pre">ez_setup.py</span></code>.</li>
</ul>
</div>
<div class="section" id="id607">
<h3>1.0<a class="headerlink" href="#id607" title="Permalink to this headline">¶</a></h3>
<p>17 Aug 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/60">Issue #60</a>: On Windows, Setuptools supports deferring to another launcher,
such as Vinay Sajip’s <a class="reference external" href="https://bitbucket.org/pypa/pylauncher">pylauncher</a>
(included with Python 3.3) to launch console and GUI scripts and not install
its own launcher executables. This experimental functionality is currently
only enabled if  the <code class="docutils literal notranslate"><span class="pre">SETUPTOOLS_LAUNCHER</span></code> environment variable is set to
“natural”. In the future, this behavior may become default, but only after
it has matured and seen substantial adoption. The <code class="docutils literal notranslate"><span class="pre">SETUPTOOLS_LAUNCHER</span></code>
also accepts “executable” to force the default behavior of creating launcher
executables.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/63">Issue #63</a>: Bootstrap script (ez_setup.py) now prefers Powershell, curl, or
wget for retrieving the Setuptools tarball for improved security of the
install. The script will still fall back to a simple <code class="docutils literal notranslate"><span class="pre">urlopen</span></code> on
platforms that do not have these tools.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/65">Issue #65</a>: Deprecated the <code class="docutils literal notranslate"><span class="pre">Features</span></code> functionality.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/52">Issue #52</a>: In <code class="docutils literal notranslate"><span class="pre">VerifyingHTTPSConn</span></code>, handle a tunnelled (proxied)
connection.</li>
</ul>
<div class="section" id="backward-incompatible-changes">
<h4>Backward-Incompatible Changes<a class="headerlink" href="#backward-incompatible-changes" title="Permalink to this headline">¶</a></h4>
<p>This release includes a couple of backward-incompatible changes, but most if
not all users will find 1.0 a drop-in replacement for 0.9.</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/50">Issue #50</a>: Normalized API of environment marker support. Specifically,
removed line number and filename from SyntaxErrors when returned from
<cite>pkg_resources.invalid_marker</cite>. Any clients depending on the specific
string representation of exceptions returned by that function may need to
be updated to account for this change.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/50">Issue #50</a>: SyntaxErrors generated by <cite>pkg_resources.invalid_marker</cite> are
normalized for cross-implementation consistency.</li>
<li>Removed <code class="docutils literal notranslate"><span class="pre">--ignore-conflicts-at-my-risk</span></code> and <code class="docutils literal notranslate"><span class="pre">--delete-conflicting</span></code>
options to easy_install. These options have been deprecated since 0.6a11.</li>
</ul>
</div>
</div>
<div class="section" id="id610">
<h3>0.9.8<a class="headerlink" href="#id610" title="Permalink to this headline">¶</a></h3>
<p>25 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/53">Issue #53</a>: Fix NameErrors in <cite>_vcs_split_rev_from_url</cite>.</li>
</ul>
</div>
<div class="section" id="id611">
<h3>0.9.7<a class="headerlink" href="#id611" title="Permalink to this headline">¶</a></h3>
<p>22 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/49">Issue #49</a>: Correct AttributeError on PyPy where a hashlib.HASH object does
not have a <cite>.name</cite> attribute.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/34">Issue #34</a>: Documentation now refers to bootstrap script in code repository
referenced by bookmark.</li>
<li>Add underscore-separated keys to environment markers (markerlib).</li>
</ul>
</div>
<div class="section" id="id612">
<h3>0.9.6<a class="headerlink" href="#id612" title="Permalink to this headline">¶</a></h3>
<p>17 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/44">Issue #44</a>: Test failure on Python 2.4 when MD5 hash doesn’t have a <cite>.name</cite>
attribute.</li>
</ul>
</div>
<div class="section" id="id613">
<h3>0.9.5<a class="headerlink" href="#id613" title="Permalink to this headline">¶</a></h3>
<p>15 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="http://bugs.python.org/issue17980">Python #17980</a>: Fix security vulnerability in SSL certificate validation.</li>
</ul>
</div>
<div class="section" id="id614">
<h3>0.9.4<a class="headerlink" href="#id614" title="Permalink to this headline">¶</a></h3>
<p>15 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/43">Issue #43</a>: Fix issue (introduced in 0.9.1) with version resolution when
upgrading over other releases of Setuptools.</li>
</ul>
</div>
<div class="section" id="id615">
<h3>0.9.3<a class="headerlink" href="#id615" title="Permalink to this headline">¶</a></h3>
<p>15 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/42">Issue #42</a>: Fix new <code class="docutils literal notranslate"><span class="pre">AttributeError</span></code> introduced in last fix.</li>
</ul>
</div>
<div class="section" id="id616">
<h3>0.9.2<a class="headerlink" href="#id616" title="Permalink to this headline">¶</a></h3>
<p>15 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/42">Issue #42</a>: Fix regression where blank checksums would trigger an
<code class="docutils literal notranslate"><span class="pre">AttributeError</span></code>.</li>
</ul>
</div>
<div class="section" id="id618">
<h3>0.9.1<a class="headerlink" href="#id618" title="Permalink to this headline">¶</a></h3>
<p>13 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/386">Distribute #386</a>: Allow other positional and keyword arguments to os.open.</li>
<li>Corrected dependency on certifi mis-referenced in 0.9.</li>
</ul>
</div>
<div class="section" id="id619">
<h3>0.9<a class="headerlink" href="#id619" title="Permalink to this headline">¶</a></h3>
<p>13 Jul 2013</p>
<ul class="simple">
<li><cite>package_index</cite> now validates hashes other than MD5 in download links.</li>
</ul>
</div>
<div class="section" id="id620">
<h3>0.8<a class="headerlink" href="#id620" title="Permalink to this headline">¶</a></h3>
<p>05 Jul 2013</p>
<ul class="simple">
<li>Code base now runs on Python 2.4 - Python 3.3 without Python 2to3
conversion.</li>
</ul>
</div>
<div class="section" id="id621">
<h3>0.7.8<a class="headerlink" href="#id621" title="Permalink to this headline">¶</a></h3>
<p>04 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/375">Distribute #375</a>: Yet another fix for yet another regression.</li>
</ul>
</div>
<div class="section" id="id622">
<h3>0.7.7<a class="headerlink" href="#id622" title="Permalink to this headline">¶</a></h3>
<p>02 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/375">Distribute #375</a>: Repair AttributeError created in last release (redo).</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/30">Issue #30</a>: Added test for get_cache_path.</li>
</ul>
</div>
<div class="section" id="id624">
<h3>0.7.6<a class="headerlink" href="#id624" title="Permalink to this headline">¶</a></h3>
<p>02 Jul 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/375">Distribute #375</a>: Repair AttributeError created in last release.</li>
</ul>
</div>
<div class="section" id="id626">
<h3>0.7.5<a class="headerlink" href="#id626" title="Permalink to this headline">¶</a></h3>
<p>29 Jun 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/21">Issue #21</a>: Restore Python 2.4 compatibility in <code class="docutils literal notranslate"><span class="pre">test_easy_install</span></code>.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/375">Distribute #375</a>: Merged additional warning from Distribute 0.6.46.</li>
<li>Now honor the environment variable
<code class="docutils literal notranslate"><span class="pre">SETUPTOOLS_DISABLE_VERSIONED_EASY_INSTALL_SCRIPT</span></code> in addition to the now
deprecated <code class="docutils literal notranslate"><span class="pre">DISTRIBUTE_DISABLE_VERSIONED_EASY_INSTALL_SCRIPT</span></code>.</li>
</ul>
</div>
<div class="section" id="id628">
<h3>0.7.4<a class="headerlink" href="#id628" title="Permalink to this headline">¶</a></h3>
<p>19 Jun 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/20">Issue #20</a>: Fix comparison of parsed SVN version on Python 3.</li>
</ul>
</div>
<div class="section" id="id629">
<h3>0.7.3<a class="headerlink" href="#id629" title="Permalink to this headline">¶</a></h3>
<p>18 Jun 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/1">Issue #1</a>: Disable installation of Windows-specific files on non-Windows systems.</li>
<li>Use new sysconfig module with Python 2.7 or &gt;=3.2.</li>
</ul>
</div>
<div class="section" id="id630">
<h3>0.7.2<a class="headerlink" href="#id630" title="Permalink to this headline">¶</a></h3>
<p>09 Jun 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/14">Issue #14</a>: Use markerlib when the <cite>parser</cite> module is not available.</li>
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/10">Issue #10</a>: <code class="docutils literal notranslate"><span class="pre">ez_setup.py</span></code> now uses HTTPS to download setuptools from PyPI.</li>
</ul>
</div>
<div class="section" id="id631">
<h3>0.7.1<a class="headerlink" href="#id631" title="Permalink to this headline">¶</a></h3>
<p>03 Jun 2013</p>
<ul class="simple">
<li>Fix NameError (<a class="reference external" href="https://github.com/pypa/setuptools/issues/3">Issue #3</a>) again - broken in bad merge.</li>
</ul>
</div>
<div class="section" id="id632">
<h3>0.7<a class="headerlink" href="#id632" title="Permalink to this headline">¶</a></h3>
<p>02 Jun 2013</p>
<ul class="simple">
<li>Merged Setuptools and Distribute. See docs/merge.txt for details.</li>
</ul>
<p>Added several features that were slated for setuptools 0.6c12:</p>
<ul class="simple">
<li>Index URL now defaults to HTTPS.</li>
<li>Added experimental environment marker support. Now clients may designate a
<a class="reference external" href="https://www.python.org/dev/peps/pep-0426/">PEP-426</a> environment marker for “extra” dependencies. Setuptools uses this
feature in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> for optional SSL and certificate validation support
on older platforms. Based on Distutils-SIG discussions, the syntax is
somewhat tentative. There should probably be a PEP with a firmer spec before
the feature should be considered suitable for use.</li>
<li>Added support for SSL certificate validation when installing packages from
an HTTPS service.</li>
</ul>
</div>
<div class="section" id="b4">
<h3>0.7b4<a class="headerlink" href="#b4" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><a class="reference external" href="https://github.com/pypa/setuptools/issues/3">Issue #3</a>: Fixed NameError in SSL support.</li>
</ul>
</div>
<div class="section" id="id635">
<h3>0.6.49<a class="headerlink" href="#id635" title="Permalink to this headline">¶</a></h3>
<p>04 Jul 2013</p>
<ul class="simple">
<li>Move warning check in <code class="docutils literal notranslate"><span class="pre">get_cache_path</span></code> to follow the directory creation
to avoid errors when the cache path does not yet exist. Fixes the error
reported in <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/375">Distribute #375</a>.</li>
</ul>
</div>
<div class="section" id="id637">
<h3>0.6.48<a class="headerlink" href="#id637" title="Permalink to this headline">¶</a></h3>
<p>02 Jul 2013</p>
<ul class="simple">
<li>Correct AttributeError in <code class="docutils literal notranslate"><span class="pre">ResourceManager.get_cache_path</span></code> introduced in
0.6.46 (redo).</li>
</ul>
</div>
<div class="section" id="id638">
<h3>0.6.47<a class="headerlink" href="#id638" title="Permalink to this headline">¶</a></h3>
<p>02 Jul 2013</p>
<ul class="simple">
<li>Correct AttributeError in <code class="docutils literal notranslate"><span class="pre">ResourceManager.get_cache_path</span></code> introduced in
0.6.46.</li>
</ul>
</div>
<div class="section" id="id639">
<h3>0.6.46<a class="headerlink" href="#id639" title="Permalink to this headline">¶</a></h3>
<p>29 Jun 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/375">Distribute #375</a>: Issue a warning if the PYTHON_EGG_CACHE or otherwise
customized egg cache location specifies a directory that’s group- or
world-writable.</li>
</ul>
</div>
<div class="section" id="id641">
<h3>0.6.45<a class="headerlink" href="#id641" title="Permalink to this headline">¶</a></h3>
<p>29 May 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/379">Distribute #379</a>: <code class="docutils literal notranslate"><span class="pre">distribute_setup.py</span></code> now traps VersionConflict as well,
restoring ability to upgrade from an older setuptools version.</li>
</ul>
</div>
<div class="section" id="id642">
<h3>0.6.44<a class="headerlink" href="#id642" title="Permalink to this headline">¶</a></h3>
<p>28 May 2013</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">distribute_setup.py</span></code> has been updated to allow Setuptools 0.7 to
satisfy use_setuptools.</li>
</ul>
</div>
<div class="section" id="id643">
<h3>0.6.43<a class="headerlink" href="#id643" title="Permalink to this headline">¶</a></h3>
<p>24 May 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/378">Distribute #378</a>: Restore support for Python 2.4 Syntax (regression in 0.6.42).</li>
</ul>
</div>
<div class="section" id="id644">
<h3>0.6.42<a class="headerlink" href="#id644" title="Permalink to this headline">¶</a></h3>
<p>24 May 2013</p>
<ul class="simple">
<li>External links finder no longer yields duplicate links.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/337">Distribute #337</a>: Moved site.py to setuptools/site-patch.py (graft of very old
patch from setuptools trunk which inspired PR <a class="reference external" href="https://github.com/pypa/setuptools/issues/31">#31</a>).</li>
</ul>
</div>
<div class="section" id="id646">
<h3>0.6.41<a class="headerlink" href="#id646" title="Permalink to this headline">¶</a></h3>
<p>24 May 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/27">Distribute #27</a>: Use public api for loading resources from zip files rather than
the private method <cite>_zip_directory_cache</cite>.</li>
<li>Added a new function <code class="docutils literal notranslate"><span class="pre">easy_install.get_win_launcher</span></code> which may be used by
third-party libraries such as buildout to get a suitable script launcher.</li>
</ul>
</div>
<div class="section" id="id647">
<h3>0.6.40<a class="headerlink" href="#id647" title="Permalink to this headline">¶</a></h3>
<p>14 May 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/376">Distribute #376</a>: brought back cli.exe and gui.exe that were deleted in the
previous release.</li>
</ul>
</div>
<div class="section" id="id648">
<h3>0.6.39<a class="headerlink" href="#id648" title="Permalink to this headline">¶</a></h3>
<p>12 May 2013</p>
<ul class="simple">
<li>Add support for console launchers on ARM platforms.</li>
<li>Fix possible issue in GUI launchers where the subsystem was not supplied to
the linker.</li>
<li>Launcher build script now refactored for robustness.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/375">Distribute #375</a>: Resources extracted from a zip egg to the file system now also
check the contents of the file against the zip contents during each
invocation of get_resource_filename.</li>
</ul>
</div>
<div class="section" id="id650">
<h3>0.6.38<a class="headerlink" href="#id650" title="Permalink to this headline">¶</a></h3>
<p>05 May 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/371">Distribute #371</a>: The launcher manifest file is now installed properly.</li>
</ul>
</div>
<div class="section" id="id651">
<h3>0.6.37<a class="headerlink" href="#id651" title="Permalink to this headline">¶</a></h3>
<p>04 May 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/143">Distribute #143</a>: Launcher scripts, including easy_install itself, are now
accompanied by a manifest on 32-bit Windows environments to avoid the
Installer Detection Technology and thus undesirable UAC elevation described
in <a class="reference external" href="http://technet.microsoft.com/en-us/library/cc709628%28WS.10%29.aspx">this Microsoft article</a>.</li>
</ul>
</div>
<div class="section" id="id652">
<h3>0.6.36<a class="headerlink" href="#id652" title="Permalink to this headline">¶</a></h3>
<p>05 Apr 2013</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/35">BB Pull Request #35</a>: In <a class="reference external" href="https://github.com/buildout/buildout/issues/64">Buildout #64</a>, it was reported that
under Python 3, installation of distutils scripts could attempt to copy
the <code class="docutils literal notranslate"><span class="pre">__pycache__</span></code> directory as a file, causing an error, apparently only
under Windows. Easy_install now skips all directories when processing
metadata scripts.</li>
</ul>
</div>
<div class="section" id="id653">
<h3>0.6.35<a class="headerlink" href="#id653" title="Permalink to this headline">¶</a></h3>
<p>16 Feb 2013</p>
<p>Note this release is backward-incompatible with distribute 0.6.23-0.6.34 in
how it parses version numbers.</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/278">Distribute #278</a>: Restored compatibility with distribute 0.6.22 and setuptools
0.6. Updated the documentation to match more closely with the version
parsing as intended in setuptools 0.6.</li>
</ul>
</div>
<div class="section" id="id654">
<h3>0.6.34<a class="headerlink" href="#id654" title="Permalink to this headline">¶</a></h3>
<p>30 Dec 2012</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/341">Distribute #341</a>: 0.6.33 fails to build under Python 2.4.</li>
</ul>
</div>
<div class="section" id="id655">
<h3>0.6.33<a class="headerlink" href="#id655" title="Permalink to this headline">¶</a></h3>
<p>29 Dec 2012</p>
<ul class="simple">
<li>Fix 2 errors with Jython 2.5.</li>
<li>Fix 1 failure with Jython 2.5 and 2.7.</li>
<li>Disable workaround for Jython scripts on Linux systems.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/336">Distribute #336</a>: <cite>setup.py</cite> no longer masks failure exit code when tests fail.</li>
<li>Fix issue in pkg_resources where try/except around a platform-dependent
import would trigger hook load failures on Mercurial. See pull request 32
for details.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/341">Distribute #341</a>: Fix a ResourceWarning.</li>
</ul>
</div>
<div class="section" id="id657">
<h3>0.6.32<a class="headerlink" href="#id657" title="Permalink to this headline">¶</a></h3>
<p>26 Nov 2012</p>
<ul class="simple">
<li>Fix test suite with Python 2.6.</li>
<li>Fix some DeprecationWarnings and ResourceWarnings.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/335">Distribute #335</a>: Backed out <cite>setup_requires</cite> superceding installed requirements
until regression can be addressed.</li>
</ul>
</div>
<div class="section" id="id658">
<h3>0.6.31<a class="headerlink" href="#id658" title="Permalink to this headline">¶</a></h3>
<p>24 Nov 2012</p>
<ul>
<li><p class="first"><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/303">Distribute #303</a>: Make sure the manifest only ever contains UTF-8 in Python 3.</p>
</li>
<li><p class="first"><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/329">Distribute #329</a>: Properly close files created by tests for compatibility with
Jython.</p>
</li>
<li><p class="first">Work around <a class="reference external" href="http://bugs.jython.org/issue1980">Jython #1980</a> and <a class="reference external" href="http://bugs.jython.org/issue1981">Jython #1981</a>.</p>
</li>
<li><p class="first"><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/334">Distribute #334</a>: Provide workaround for packages that reference <cite>sys.__stdout__</cite>
such as numpy does. This change should address
<a class="reference external" href="https://github.com/pypa/setuptools/issues/359">virtualenv `#359</a> &lt;<a class="reference external" href="https://github.com/pypa/virtualenv/issues/359">https://github.com/pypa/virtualenv/issues/359</a>&gt;`_ as long
as the system encoding is UTF-8 or the IO encoding is specified in the
environment, i.e.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">PYTHONIOENCODING</span><span class="o">=</span><span class="n">utf8</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">numpy</span>
</pre></div>
</div>
</li>
<li><p class="first">Fix for encoding issue when installing from Windows executable on Python 3.</p>
</li>
<li><p class="first"><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/323">Distribute #323</a>: Allow <cite>setup_requires</cite> requirements to supercede installed
requirements. Added some new keyword arguments to existing pkg_resources
methods. Also had to updated how __path__ is handled for namespace packages
to ensure that when a new egg distribution containing a namespace package is
placed on sys.path, the entries in __path__ are found in the same order they
would have been in had that egg been on the path when pkg_resources was
first imported.</p>
</li>
</ul>
</div>
<div class="section" id="id660">
<h3>0.6.30<a class="headerlink" href="#id660" title="Permalink to this headline">¶</a></h3>
<p>22 Oct 2012</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/328">Distribute #328</a>: Clean up temporary directories in distribute_setup.py.</li>
<li>Fix fatal bug in distribute_setup.py.</li>
</ul>
</div>
<div class="section" id="id661">
<h3>0.6.29<a class="headerlink" href="#id661" title="Permalink to this headline">¶</a></h3>
<p>21 Oct 2012</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/pypa/setuptools/pull-request/14">BB Pull Request #14</a>: Honor file permissions in zip files.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/327">Distribute #327</a>: Merged pull request <a class="reference external" href="https://github.com/pypa/setuptools/issues/24">#24</a> to fix a dependency problem with pip.</li>
<li>Merged pull request <a class="reference external" href="https://github.com/pypa/setuptools/issues/23">#23</a> to fix <a class="reference external" href="https://github.com/pypa/virtualenv/issues/301">https://github.com/pypa/virtualenv/issues/301</a>.</li>
<li>If Sphinx is installed, the <cite>upload_docs</cite> command now runs <cite>build_sphinx</cite>
to produce uploadable documentation.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/326">Distribute #326</a>: <cite>upload_docs</cite> provided mangled auth credentials under Python 3.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/320">Distribute #320</a>: Fix check for “createable” in distribute_setup.py.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/305">Distribute #305</a>: Remove a warning that was triggered during normal operations.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/311">Distribute #311</a>: Print metadata in UTF-8 independent of platform.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/303">Distribute #303</a>: Read manifest file with UTF-8 encoding under Python 3.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/301">Distribute #301</a>: Allow to run tests of namespace packages when using 2to3.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/304">Distribute #304</a>: Prevent import loop in site.py under Python 3.3.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/283">Distribute #283</a>: Reenable scanning of <cite>*.pyc</cite> / <cite>*.pyo</cite> files on Python 3.3.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/299">Distribute #299</a>: The develop command didn’t work on Python 3, when using 2to3,
as the egg link would go to the Python 2 source. Linking to the 2to3’d code
in build/lib makes it work, although you will have to rebuild the module
before testing it.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/306">Distribute #306</a>: Even if 2to3 is used, we build in-place under Python 2.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/307">Distribute #307</a>: Prints the full path when .svn/entries is broken.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/313">Distribute #313</a>: Support for sdist subcommands (Python 2.7)</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/314">Distribute #314</a>: test_local_index() would fail an OS X.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/310">Distribute #310</a>: Non-ascii characters in a namespace __init__.py causes errors.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/218">Distribute #218</a>: Improved documentation on behavior of <cite>package_data</cite> and
<cite>include_package_data</cite>. Files indicated by <cite>package_data</cite> are now included
in the manifest.</li>
<li><cite>distribute_setup.py</cite> now allows a <cite>–download-base</cite> argument for retrieving
distribute from a specified location.</li>
</ul>
</div>
<div class="section" id="id665">
<h3>0.6.28<a class="headerlink" href="#id665" title="Permalink to this headline">¶</a></h3>
<p>22 Jul 2012</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/294">Distribute #294</a>: setup.py can now be invoked from any directory.</li>
<li>Scripts are now installed honoring the umask.</li>
<li>Added support for .dist-info directories.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/283">Distribute #283</a>: Fix and disable scanning of <cite>*.pyc</cite> / <cite>*.pyo</cite> files on
Python 3.3.</li>
</ul>
</div>
<div class="section" id="id667">
<h3>0.6.27<a class="headerlink" href="#id667" title="Permalink to this headline">¶</a></h3>
<p>18 May 2012</p>
<ul class="simple">
<li>Support current snapshots of CPython 3.3.</li>
<li>Distribute now recognizes README.rst as a standard, default readme file.</li>
<li>Exclude ‘encodings’ modules when removing modules from sys.modules.
Workaround for <a class="reference external" href="https://github.com/pypa/setuptools/issues/285">#285</a>.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/231">Distribute #231</a>: Don’t fiddle with system python when used with buildout
(bootstrap.py)</li>
</ul>
</div>
<div class="section" id="id669">
<h3>0.6.26<a class="headerlink" href="#id669" title="Permalink to this headline">¶</a></h3>
<p>08 Apr 2012</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/183">Distribute #183</a>: Symlinked files are now extracted from source distributions.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/227">Distribute #227</a>: Easy_install fetch parameters are now passed during the
installation of a source distribution; now fulfillment of setup_requires
dependencies will honor the parameters passed to easy_install.</li>
</ul>
</div>
<div class="section" id="id670">
<h3>0.6.25<a class="headerlink" href="#id670" title="Permalink to this headline">¶</a></h3>
<p>08 Feb 2012</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/258">Distribute #258</a>: Workaround a cache issue</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/260">Distribute #260</a>: distribute_setup.py now accepts the –user parameter for
Python 2.6 and later.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/262">Distribute #262</a>: package_index.open_with_auth no longer throws LookupError
on Python 3.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/269">Distribute #269</a>: AttributeError when an exception occurs reading Manifest.in
on late releases of Python.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/272">Distribute #272</a>: Prevent TypeError when namespace package names are unicode
and single-install-externally-managed is used. Also fixes PIP issue
449.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/273">Distribute #273</a>: Legacy script launchers now install with Python2/3 support.</li>
</ul>
</div>
<div class="section" id="id671">
<h3>0.6.24<a class="headerlink" href="#id671" title="Permalink to this headline">¶</a></h3>
<p>14 Oct 2011</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/249">Distribute #249</a>: Added options to exclude 2to3 fixers</li>
</ul>
</div>
<div class="section" id="id672">
<h3>0.6.23<a class="headerlink" href="#id672" title="Permalink to this headline">¶</a></h3>
<p>22 Sep 2011</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/244">Distribute #244</a>: Fixed a test</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/243">Distribute #243</a>: Fixed a test</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/239">Distribute #239</a>: Fixed a test</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/240">Distribute #240</a>: Fixed a test</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/241">Distribute #241</a>: Fixed a test</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/237">Distribute #237</a>: Fixed a test</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/238">Distribute #238</a>: easy_install now uses 64bit executable wrappers on 64bit Python</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/208">Distribute #208</a>: Fixed parsed_versions, it now honors post-releases as noted in the documentation</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/207">Distribute #207</a>: Windows cli and gui wrappers pass CTRL-C to child python process</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/227">Distribute #227</a>: easy_install now passes its arguments to setup.py bdist_egg</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/225">Distribute #225</a>: Fixed a NameError on Python 2.5, 2.4</li>
</ul>
</div>
<div class="section" id="id674">
<h3>0.6.21<a class="headerlink" href="#id674" title="Permalink to this headline">¶</a></h3>
<p>20 Aug 2011</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/225">Distribute #225</a>: FIxed a regression on py2.4</li>
</ul>
</div>
<div class="section" id="id676">
<h3>0.6.20<a class="headerlink" href="#id676" title="Permalink to this headline">¶</a></h3>
<p>18 Aug 2011</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/135">Distribute #135</a>: Include url in warning when processing URLs in package_index.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/212">Distribute #212</a>: Fix issue where easy_instal fails on Python 3 on windows installer.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/213">Distribute #213</a>: Fix typo in documentation.</li>
</ul>
</div>
<div class="section" id="id677">
<h3>0.6.19<a class="headerlink" href="#id677" title="Permalink to this headline">¶</a></h3>
<p>02 Jun 2011</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/206">Distribute #206</a>: AttributeError: ‘HTTPMessage’ object has no attribute ‘getheaders’</li>
</ul>
</div>
<div class="section" id="id678">
<h3>0.6.18<a class="headerlink" href="#id678" title="Permalink to this headline">¶</a></h3>
<p>01 Jun 2011</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/210">Distribute #210</a>: Fixed a regression introduced by <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/204">Distribute #204</a> fix.</li>
</ul>
</div>
<div class="section" id="id679">
<h3>0.6.17<a class="headerlink" href="#id679" title="Permalink to this headline">¶</a></h3>
<p>30 May 2011</p>
<ul class="simple">
<li>Support ‘DISTRIBUTE_DISABLE_VERSIONED_EASY_INSTALL_SCRIPT’ environment
variable to allow to disable installation of easy_install-${version} script.</li>
<li>Support Python &gt;=3.1.4 and &gt;=3.2.1.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/204">Distribute #204</a>: Don’t try to import the parent of a namespace package in
declare_namespace</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/196">Distribute #196</a>: Tolerate responses with multiple Content-Length headers</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/205">Distribute #205</a>: Sandboxing doesn’t preserve working_set. Leads to setup_requires
problems.</li>
</ul>
</div>
<div class="section" id="id681">
<h3>0.6.16<a class="headerlink" href="#id681" title="Permalink to this headline">¶</a></h3>
<p>28 Apr 2011</p>
<ul class="simple">
<li>Builds sdist gztar even on Windows (avoiding <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/193">Distribute #193</a>).</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/192">Distribute #192</a>: Fixed metadata omitted on Windows when package_dir
specified with forward-slash.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/195">Distribute #195</a>: Cython build support.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/200">Distribute #200</a>: Issues with recognizing 64-bit packages on Windows.</li>
</ul>
</div>
<div class="section" id="id682">
<h3>0.6.15<a class="headerlink" href="#id682" title="Permalink to this headline">¶</a></h3>
<p>12 Mar 2011</p>
<ul class="simple">
<li>Fixed typo in bdist_egg</li>
<li>Several issues under Python 3 has been solved.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/146">Distribute #146</a>: Fixed missing DLL files after easy_install of windows exe package.</li>
</ul>
</div>
<div class="section" id="id683">
<h3>0.6.14<a class="headerlink" href="#id683" title="Permalink to this headline">¶</a></h3>
<p>15 Jul 2010</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/170">Distribute #170</a>: Fixed unittest failure. Thanks to Toshio.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/171">Distribute #171</a>: Fixed race condition in unittests cause deadlocks in test suite.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/143">Distribute #143</a>: Fixed a lookup issue with easy_install.
Thanks to David and Zooko.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/174">Distribute #174</a>: Fixed the edit mode when its used with setuptools itself</li>
</ul>
</div>
<div class="section" id="id685">
<h3>0.6.13<a class="headerlink" href="#id685" title="Permalink to this headline">¶</a></h3>
<p>31 May 2010</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/160">Distribute #160</a>: 2.7 gives ValueError(“Invalid IPv6 URL”)</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/150">Distribute #150</a>: Fixed using ~/.local even in a –no-site-packages virtualenv</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/163">Distribute #163</a>: scan index links before external links, and don’t use the md5 when
comparing two distributions</li>
</ul>
</div>
<div class="section" id="id686">
<h3>0.6.12<a class="headerlink" href="#id686" title="Permalink to this headline">¶</a></h3>
<p>06 May 2010</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/149">Distribute #149</a>: Fixed various failures on 2.3/2.4</li>
</ul>
</div>
<div class="section" id="id687">
<h3>0.6.11<a class="headerlink" href="#id687" title="Permalink to this headline">¶</a></h3>
<p>06 May 2010</p>
<ul class="simple">
<li>Found another case of SandboxViolation - fixed</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/15">Distribute #15</a> and <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/48">Distribute #48</a>: Introduced a socket timeout of 15 seconds on url openings</li>
<li>Added indexsidebar.html into MANIFEST.in</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/108">Distribute #108</a>: Fixed TypeError with Python3.1</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/121">Distribute #121</a>: Fixed –help install command trying to actually install.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/112">Distribute #112</a>: Added an os.makedirs so that Tarek’s solution will work.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/133">Distribute #133</a>: Added –no-find-links to easy_install</li>
<li>Added easy_install –user</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/100">Distribute #100</a>: Fixed develop –user not taking ‘.’ in PYTHONPATH into account</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/134">Distribute #134</a>: removed spurious UserWarnings. Patch by VanLindberg</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/138">Distribute #138</a>: cant_write_to_target error when setup_requires is used.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/147">Distribute #147</a>: respect the sys.dont_write_bytecode flag</li>
</ul>
</div>
<div class="section" id="id688">
<h3>0.6.10<a class="headerlink" href="#id688" title="Permalink to this headline">¶</a></h3>
<p>12 Dec 2009</p>
<ul class="simple">
<li>Reverted change made for the DistributionNotFound exception because
zc.buildout uses the exception message to get the name of the
distribution.</li>
</ul>
</div>
<div class="section" id="id689">
<h3>0.6.9<a class="headerlink" href="#id689" title="Permalink to this headline">¶</a></h3>
<p>12 Dec 2009</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/90">Distribute #90</a>: unknown setuptools version can be added in the working set</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/87">Distribute #87</a>: setupt.py doesn’t try to convert distribute_setup.py anymore
Initial Patch by arfrever.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/89">Distribute #89</a>: added a side bar with a download link to the doc.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/86">Distribute #86</a>: fixed missing sentence in pkg_resources doc.</li>
<li>Added a nicer error message when a DistributionNotFound is raised.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/80">Distribute #80</a>: test_develop now works with Python 3.1</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/93">Distribute #93</a>: upload_docs now works if there is an empty sub-directory.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/70">Distribute #70</a>: exec bit on non-exec files</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/99">Distribute #99</a>: now the standalone easy_install command doesn’t uses a
“setup.cfg” if any exists in the working directory. It will use it
only if triggered by <code class="docutils literal notranslate"><span class="pre">install_requires</span></code> from a setup.py call
(install, develop, etc).</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/101">Distribute #101</a>: Allowing <code class="docutils literal notranslate"><span class="pre">os.devnull</span></code> in Sandbox</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/92">Distribute #92</a>: Fixed the “no eggs” found error with MacPort
(platform.mac_ver() fails)</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/103">Distribute #103</a>: test_get_script_header_jython_workaround not run
anymore under py3 with C or POSIX local. Contributed by Arfrever.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/104">Distribute #104</a>: remvoved the assertion when the installation fails,
with a nicer message for the end user.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/100">Distribute #100</a>: making sure there’s no SandboxViolation when
the setup script patches setuptools.</li>
</ul>
</div>
<div class="section" id="id691">
<h3>0.6.8<a class="headerlink" href="#id691" title="Permalink to this headline">¶</a></h3>
<p>01 Nov 2009</p>
<ul class="simple">
<li>Added “check_packages” in dist. (added in Setuptools 0.6c11)</li>
<li>Fixed the DONT_PATCH_SETUPTOOLS state.</li>
</ul>
</div>
<div class="section" id="id692">
<h3>0.6.7<a class="headerlink" href="#id692" title="Permalink to this headline">¶</a></h3>
<p>01 Nov 2009</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/58">Distribute #58</a>: Added –user support to the develop command</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/11">Distribute #11</a>: Generated scripts now wrap their call to the script entry point
in the standard “if name == ‘main’”</li>
<li>Added the ‘DONT_PATCH_SETUPTOOLS’ environment variable, so virtualenv
can drive an installation that doesn’t patch a global setuptools.</li>
<li>Reviewed unladen-swallow specific change from
<a class="reference external" href="http://code.google.com/p/unladen-swallow/source/detail?spec=svn875&amp;r=719">http://code.google.com/p/unladen-swallow/source/detail?spec=svn875&amp;r=719</a>
and determined that it no longer applies. Distribute should work fine with
Unladen Swallow 2009Q3.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/21">Distribute #21</a>: Allow PackageIndex.open_url to gracefully handle all cases of a
httplib.HTTPException instead of just InvalidURL and BadStatusLine.</li>
<li>Removed virtual-python.py from this distribution and updated documentation
to point to the actively maintained virtualenv instead.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/64">Distribute #64</a>: use_setuptools no longer rebuilds the distribute egg every
time it is run</li>
<li>use_setuptools now properly respects the requested version</li>
<li>use_setuptools will no longer try to import a distribute egg for the
wrong Python version</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/74">Distribute #74</a>: no_fake should be True by default.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/72">Distribute #72</a>: avoid a bootstrapping issue with easy_install -U</li>
</ul>
</div>
<div class="section" id="id693">
<h3>0.6.6<a class="headerlink" href="#id693" title="Permalink to this headline">¶</a></h3>
<p>15 Oct 2009</p>
<ul class="simple">
<li>Unified the bootstrap file so it works on both py2.x and py3k without 2to3
(patch by Holger Krekel)</li>
</ul>
</div>
<div class="section" id="id694">
<h3>0.6.5<a class="headerlink" href="#id694" title="Permalink to this headline">¶</a></h3>
<p>15 Oct 2009</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/65">Distribute #65</a>: cli.exe and gui.exe are now generated at build time,
depending on the platform in use.</li>
<li><a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/67">Distribute #67</a>: Fixed doc typo (<a class="reference external" href="https://www.python.org/dev/peps/pep-0381/">PEP 381</a>/<a class="reference external" href="https://www.python.org/dev/peps/pep-0382/">PEP 382</a>).</li>
<li>Distribute no longer shadows setuptools if we require a 0.7-series
setuptools. And an error is raised when installing a 0.7 setuptools with
distribute.</li>
<li>When run from within buildout, no attempt is made to modify an existing
setuptools egg, whether in a shared egg directory or a system setuptools.</li>
<li>Fixed a hole in sandboxing allowing builtin file to write outside of
the sandbox.</li>
</ul>
</div>
<div class="section" id="id695">
<h3>0.6.4<a class="headerlink" href="#id695" title="Permalink to this headline">¶</a></h3>
<p>10 Oct 2009</p>
<ul class="simple">
<li>Added the generation of <cite>distribute_setup_3k.py</cite> during the release.
This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/52">Distribute #52</a>.</li>
<li>Added an upload_docs command to easily upload project documentation to
PyPI’s <a class="reference external" href="https://pythonhosted.org">https://pythonhosted.org</a>. This close issue <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/56">Distribute #56</a>.</li>
<li>Fixed a bootstrap bug on the use_setuptools() API.</li>
</ul>
</div>
<div class="section" id="id696">
<h3>0.6.3<a class="headerlink" href="#id696" title="Permalink to this headline">¶</a></h3>
<p>27 Sep 2009</p>
<div class="section" id="setuptools">
<h4>setuptools<a class="headerlink" href="#setuptools" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Fixed a bunch of calls to file() that caused crashes on Python 3.</li>
</ul>
</div>
<div class="section" id="bootstrapping">
<h4>bootstrapping<a class="headerlink" href="#bootstrapping" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Fixed a bug in sorting that caused bootstrap to fail on Python 3.</li>
</ul>
</div>
</div>
<div class="section" id="id697">
<h3>0.6.2<a class="headerlink" href="#id697" title="Permalink to this headline">¶</a></h3>
<p>26 Sep 2009</p>
<div class="section" id="id698">
<h4>setuptools<a class="headerlink" href="#id698" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Added Python 3 support; see docs/python3.txt.
This closes <a class="reference external" href="http://bugs.python.org/setuptools/issue39">Old Setuptools #39</a>.</li>
<li>Added option to run 2to3 automatically when installing on Python 3.
This closes issue <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/31">Distribute #31</a>.</li>
<li>Fixed invalid usage of requirement.parse, that broke develop -d.
This closes <a class="reference external" href="http://bugs.python.org/setuptools/issue44">Old Setuptools #44</a>.</li>
<li>Fixed script launcher for 64-bit Windows.
This closes <a class="reference external" href="http://bugs.python.org/setuptools/issue2">Old Setuptools #2</a>.</li>
<li>KeyError when compiling extensions.
This closes <a class="reference external" href="http://bugs.python.org/setuptools/issue41">Old Setuptools #41</a>.</li>
</ul>
</div>
<div class="section" id="id699">
<h4>bootstrapping<a class="headerlink" href="#id699" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Fixed bootstrap not working on Windows. This closes issue <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/49">Distribute #49</a>.</li>
<li>Fixed 2.6 dependencies. This closes issue <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/50">Distribute #50</a>.</li>
<li>Make sure setuptools is patched when running through easy_install
This closes <a class="reference external" href="http://bugs.python.org/setuptools/issue40">Old Setuptools #40</a>.</li>
</ul>
</div>
</div>
<div class="section" id="id700">
<h3>0.6.1<a class="headerlink" href="#id700" title="Permalink to this headline">¶</a></h3>
<p>08 Sep 2009</p>
<div class="section" id="id701">
<h4>setuptools<a class="headerlink" href="#id701" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>package_index.urlopen now catches BadStatusLine and malformed url errors.
This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/16">Distribute #16</a> and <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/18">Distribute #18</a>.</li>
<li>zip_ok is now False by default. This closes <a class="reference external" href="http://bugs.python.org/setuptools/issue33">Old Setuptools #33</a>.</li>
<li>Fixed invalid URL error catching. <a class="reference external" href="http://bugs.python.org/setuptools/issue20">Old Setuptools #20</a>.</li>
<li>Fixed invalid bootstraping with easy_install installation (<a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/40">Distribute #40</a>).
Thanks to Florian Schulze for the help.</li>
<li>Removed buildout/bootstrap.py. A new repository will create a specific
bootstrap.py script.</li>
</ul>
</div>
<div class="section" id="id702">
<h4>bootstrapping<a class="headerlink" href="#id702" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>The boostrap process leave setuptools alone if detected in the system
and –root or –prefix is provided, but is not in the same location.
This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/10">Distribute #10</a>.</li>
</ul>
</div>
</div>
<div class="section" id="id703">
<h3>0.6<a class="headerlink" href="#id703" title="Permalink to this headline">¶</a></h3>
<p>09 Aug 2009</p>
<div class="section" id="id704">
<h4>setuptools<a class="headerlink" href="#id704" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Packages required at build time where not fully present at install time.
This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/12">Distribute #12</a>.</li>
<li>Protected against failures in tarfile extraction. This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/10">Distribute #10</a>.</li>
<li>Made Jython api_tests.txt doctest compatible. This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/7">Distribute #7</a>.</li>
<li>sandbox.py replaced builtin type file with builtin function open. This
closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/6">Distribute #6</a>.</li>
<li>Immediately close all file handles. This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/3">Distribute #3</a>.</li>
<li>Added compatibility with Subversion 1.6. This references <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/1">Distribute #1</a>.</li>
</ul>
</div>
<div class="section" id="pkg-resources">
<h4>pkg_resources<a class="headerlink" href="#pkg-resources" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Avoid a call to /usr/bin/sw_vers on OSX and use the official platform API
instead. Based on a patch from ronaldoussoren. This closes issue <a class="reference external" href="https://github.com/pypa/setuptools/issues/5">#5</a>.</li>
<li>Fixed a SandboxViolation for mkdir that could occur in certain cases.
This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/13">Distribute #13</a>.</li>
<li>Allow to find_on_path on systems with tight permissions to fail gracefully.
This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/9">Distribute #9</a>.</li>
<li>Corrected inconsistency between documentation and code of add_entry.
This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/8">Distribute #8</a>.</li>
<li>Immediately close all file handles. This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/3">Distribute #3</a>.</li>
</ul>
</div>
<div class="section" id="easy-install">
<h4>easy_install<a class="headerlink" href="#easy-install" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Immediately close all file handles. This closes <a class="reference external" href="https://bitbucket.org/tarek/distribute/issue/3">Distribute #3</a>.</li>
</ul>
</div>
</div>
<div class="section" id="c9">
<h3>0.6c9<a class="headerlink" href="#c9" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fixed a missing files problem when using Windows source distributions on
non-Windows platforms, due to distutils not handling manifest file line
endings correctly.</li>
<li>Updated Pyrex support to work with Pyrex 0.9.6 and higher.</li>
<li>Minor changes for Jython compatibility, including skipping tests that can’t
work on Jython.</li>
<li>Fixed not installing eggs in <code class="docutils literal notranslate"><span class="pre">install_requires</span></code> if they were also used for
<code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> or <code class="docutils literal notranslate"><span class="pre">tests_require</span></code>.</li>
<li>Fixed not fetching eggs in <code class="docutils literal notranslate"><span class="pre">install_requires</span></code> when running tests.</li>
<li>Allow <code class="docutils literal notranslate"><span class="pre">ez_setup.use_setuptools()</span></code> to upgrade existing setuptools
installations when called from a standalone <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>.</li>
<li>Added a warning if a namespace package is declared, but its parent package
is not also declared as a namespace.</li>
<li>Support Subversion 1.5</li>
<li>Removed use of deprecated <code class="docutils literal notranslate"><span class="pre">md5</span></code> module if <code class="docutils literal notranslate"><span class="pre">hashlib</span></code> is available</li>
<li>Fixed <code class="docutils literal notranslate"><span class="pre">bdist_wininst</span> <span class="pre">upload</span></code> trying to upload the <code class="docutils literal notranslate"><span class="pre">.exe</span></code> twice</li>
<li>Fixed <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> putting a <code class="docutils literal notranslate"><span class="pre">native_libs.txt</span></code> in the source package’s
<code class="docutils literal notranslate"><span class="pre">.egg-info</span></code>, when it should only be in the built egg’s <code class="docutils literal notranslate"><span class="pre">EGG-INFO</span></code>.</li>
<li>Ensure that _full_name is set on all shared libs before extensions are
checked for shared lib usage.  (Fixes a bug in the experimental shared
library build support.)</li>
<li>Fix to allow unpacked eggs containing native libraries to fail more
gracefully under Google App Engine (with an <code class="docutils literal notranslate"><span class="pre">ImportError</span></code> loading the
C-based module, instead of getting a <code class="docutils literal notranslate"><span class="pre">NameError</span></code>).</li>
<li>Fixed <code class="docutils literal notranslate"><span class="pre">win32.exe</span></code> support for .pth files, so unnecessary directory nesting
is flattened out in the resulting egg.  (There was a case-sensitivity
problem that affected some distributions, notably <code class="docutils literal notranslate"><span class="pre">pywin32</span></code>.)</li>
<li>Prevent <code class="docutils literal notranslate"><span class="pre">--help-commands</span></code> and other junk from showing under Python 2.5
when running <code class="docutils literal notranslate"><span class="pre">easy_install</span> <span class="pre">--help</span></code>.</li>
<li>Fixed GUI scripts sometimes not executing on Windows</li>
<li>Fixed not picking up dependency links from recursive dependencies.</li>
<li>Only make <code class="docutils literal notranslate"><span class="pre">.py</span></code>, <code class="docutils literal notranslate"><span class="pre">.dll</span></code> and <code class="docutils literal notranslate"><span class="pre">.so</span></code> files executable when unpacking eggs</li>
<li>Changes for Jython compatibility</li>
<li>Improved error message when a requirement is also a directory name, but the
specified directory is not a source package.</li>
<li>Fixed <code class="docutils literal notranslate"><span class="pre">--allow-hosts</span></code> option blocking <code class="docutils literal notranslate"><span class="pre">file:</span></code> URLs</li>
<li>Fixed HTTP SVN detection failing when the page title included a project
name (e.g. on SourceForge-hosted SVN)</li>
<li>Fix Jython script installation to handle <code class="docutils literal notranslate"><span class="pre">#!</span></code> lines better when
<code class="docutils literal notranslate"><span class="pre">sys.executable</span></code> is a script.</li>
<li>Removed use of deprecated <code class="docutils literal notranslate"><span class="pre">md5</span></code> module if <code class="docutils literal notranslate"><span class="pre">hashlib</span></code> is available</li>
<li>Keep site directories (e.g. <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>) from being included in
<code class="docutils literal notranslate"><span class="pre">.pth</span></code> files.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="c7">
<h3>0.6c7<a class="headerlink" href="#c7" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fixed <code class="docutils literal notranslate"><span class="pre">distutils.filelist.findall()</span></code> crashing on broken symlinks, and
<code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command failing on new, uncommitted SVN directories.</li>
<li>Fix import problems with nested namespace packages installed via
<code class="docutils literal notranslate"><span class="pre">--root</span></code> or <code class="docutils literal notranslate"><span class="pre">--single-version-externally-managed</span></code>, due to the
parent package not having the child package as an attribute.</li>
<li><code class="docutils literal notranslate"><span class="pre">ftp:</span></code> download URLs now work correctly.</li>
<li>The default <code class="docutils literal notranslate"><span class="pre">--index-url</span></code> is now <code class="docutils literal notranslate"><span class="pre">https://pypi.python.org/simple</span></code>, to use
the Python Package Index’s new simpler (and faster!) REST API.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="c6">
<h3>0.6c6<a class="headerlink" href="#c6" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added <code class="docutils literal notranslate"><span class="pre">--egg-path</span></code> option to <code class="docutils literal notranslate"><span class="pre">develop</span></code> command, allowing you to force
<code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> files to use relative paths (allowing them to be shared across
platforms on a networked drive).</li>
<li>Fix not building binary RPMs correctly.</li>
<li>Fix “eggsecutables” (such as setuptools’ own egg) only being runnable with
bash-compatible shells.</li>
<li>Fix <code class="docutils literal notranslate"><span class="pre">#!</span></code> parsing problems in Windows <code class="docutils literal notranslate"><span class="pre">.exe</span></code> script wrappers, when there
was whitespace inside a quoted argument or at the end of the <code class="docutils literal notranslate"><span class="pre">#!</span></code> line
(a regression introduced in 0.6c4).</li>
<li>Fix <code class="docutils literal notranslate"><span class="pre">test</span></code> command possibly failing if an older version of the project
being tested was installed on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> ahead of the test source
directory.</li>
<li>Fix <code class="docutils literal notranslate"><span class="pre">find_packages()</span></code> treating <code class="docutils literal notranslate"><span class="pre">ez_setup</span></code> and directories with <code class="docutils literal notranslate"><span class="pre">.</span></code> in
their names as packages.</li>
<li>EasyInstall no longer aborts the installation process if a URL it wants to
retrieve can’t be downloaded, unless the URL is an actual package download.
Instead, it issues a warning and tries to keep going.</li>
<li>Fixed distutils-style scripts originally built on Windows having their line
endings doubled when installed on any platform.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">--local-snapshots-ok</span></code> flag, to allow building eggs from projects
installed using <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code>.</li>
<li>Fixed not HTML-decoding URLs scraped from web pages</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="c5">
<h3>0.6c5<a class="headerlink" href="#c5" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fix uploaded <code class="docutils literal notranslate"><span class="pre">bdist_rpm</span></code> packages being described as <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code>
packages under Python versions less than 2.5.</li>
<li>Fix uploaded <code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code> packages being described as suitable for
“any” version by Python 2.5, even if a <code class="docutils literal notranslate"><span class="pre">--target-version</span></code> was specified.</li>
<li>Fixed <code class="docutils literal notranslate"><span class="pre">.dll</span></code> files on Cygwin not having executable permissions when an egg
is installed unzipped.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="c4">
<h3>0.6c4<a class="headerlink" href="#c4" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Overhauled Windows script wrapping to support <code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code> better.
Scripts installed with <code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code> will always use <code class="docutils literal notranslate"><span class="pre">#!python.exe</span></code> or
<code class="docutils literal notranslate"><span class="pre">#!pythonw.exe</span></code> as the executable name (even when built on non-Windows
platforms!), and the wrappers will look for the executable in the script’s
parent directory (which should find the right version of Python).</li>
<li>Fix <code class="docutils literal notranslate"><span class="pre">upload</span></code> command not uploading files built by <code class="docutils literal notranslate"><span class="pre">bdist_rpm</span></code> or
<code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code> under Python 2.3 and 2.4.</li>
<li>Add support for “eggsecutable” headers: a <code class="docutils literal notranslate"><span class="pre">#!/bin/sh</span></code> script that is
prepended to an <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file to allow it to be run as a script on Unix-ish
platforms.  (This is mainly so that setuptools itself can have a single-file
installer on Unix, without doing multiple downloads, dealing with firewalls,
etc.)</li>
<li>Fix problem with empty revision numbers in Subversion 1.4 <code class="docutils literal notranslate"><span class="pre">entries</span></code> files</li>
<li>Use cross-platform relative paths in <code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> when doing
<code class="docutils literal notranslate"><span class="pre">develop</span></code> and the source directory is a subdirectory of the installation
target directory.</li>
<li>Fix a problem installing eggs with a system packaging tool if the project
contained an implicit namespace package; for example if the <code class="docutils literal notranslate"><span class="pre">setup()</span></code>
listed a namespace package <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code> without explicitly listing <code class="docutils literal notranslate"><span class="pre">foo</span></code>
as a namespace package.</li>
<li>Added support for HTTP “Basic” authentication using <code class="docutils literal notranslate"><span class="pre">http://user:pass&#64;host</span></code>
URLs.  If a password-protected page contains links to the same host (and
protocol), those links will inherit the credentials used to access the
original page.</li>
<li>Removed all special support for Sourceforge mirrors, as Sourceforge’s
mirror system now works well for non-browser downloads.</li>
<li>Fixed not recognizing <code class="docutils literal notranslate"><span class="pre">win32.exe</span></code> installers that included a custom
bitmap.</li>
<li>Fixed not allowing <code class="docutils literal notranslate"><span class="pre">os.open()</span></code> of paths outside the sandbox, even if they
are opened read-only (e.g. reading <code class="docutils literal notranslate"><span class="pre">/dev/urandom</span></code> for random numbers, as
is done by <code class="docutils literal notranslate"><span class="pre">os.urandom()</span></code> on some platforms).</li>
<li>Fixed a problem with <code class="docutils literal notranslate"><span class="pre">.pth</span></code> testing on Windows when <code class="docutils literal notranslate"><span class="pre">sys.executable</span></code>
has a space in it (e.g., the user installed Python to a <code class="docutils literal notranslate"><span class="pre">Program</span> <span class="pre">Files</span></code>
directory).</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="c3">
<h3>0.6c3<a class="headerlink" href="#c3" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fixed breakages caused by Subversion 1.4’s new “working copy” format</li>
<li>You can once again use “python -m easy_install” with Python 2.4 and above.</li>
<li>Python 2.5 compatibility fixes added.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="c2">
<h3>0.6c2<a class="headerlink" href="#c2" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>The <code class="docutils literal notranslate"><span class="pre">ez_setup</span></code> module displays the conflicting version of setuptools (and
its installation location) when a script requests a version that’s not
available.</li>
<li>Running <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code> on a setuptools-using project will now install
setuptools if needed, instead of only downloading the egg.</li>
<li>Windows script wrappers now support quoted arguments and arguments
containing spaces.  (Patch contributed by Jim Fulton.)</li>
<li>The <code class="docutils literal notranslate"><span class="pre">ez_setup.py</span></code> script now actually works when you put a setuptools
<code class="docutils literal notranslate"><span class="pre">.egg</span></code> alongside it for bootstrapping an offline machine.</li>
<li>A writable installation directory on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> is no longer required to
download and extract a source distribution using <code class="docutils literal notranslate"><span class="pre">--editable</span></code>.</li>
<li>Generated scripts now use <code class="docutils literal notranslate"><span class="pre">-x</span></code> on the <code class="docutils literal notranslate"><span class="pre">#!</span></code> line when <code class="docutils literal notranslate"><span class="pre">sys.executable</span></code>
contains non-ASCII characters, to prevent deprecation warnings about an
unspecified encoding when the script is run.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="c1">
<h3>0.6c1<a class="headerlink" href="#c1" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fixed <code class="docutils literal notranslate"><span class="pre">AttributeError</span></code> when trying to download a <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code>
dependency when a distribution lacks a <code class="docutils literal notranslate"><span class="pre">dependency_links</span></code> setting.</li>
<li>Made <code class="docutils literal notranslate"><span class="pre">zip-safe</span></code> and <code class="docutils literal notranslate"><span class="pre">not-zip-safe</span></code> flag files contain a single byte, so
as to play better with packaging tools that complain about zero-length
files.</li>
<li>Made <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span></code> respect the <code class="docutils literal notranslate"><span class="pre">--no-deps</span></code> option, which it
previously was ignoring.</li>
<li>Support <code class="docutils literal notranslate"><span class="pre">extra_path</span></code> option to <code class="docutils literal notranslate"><span class="pre">setup()</span></code> when <code class="docutils literal notranslate"><span class="pre">install</span></code> is run in
backward-compatibility mode.</li>
<li>Source distributions now always include a <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> file that explicitly
sets <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> options such that they produce an identical version number
to the source distribution’s version number.  (Previously, the default
version number could be different due to the use of <code class="docutils literal notranslate"><span class="pre">--tag-date</span></code>, or if
the version was overridden on the command line that built the source
distribution.)</li>
<li>EasyInstall now includes setuptools version information in the
<code class="docutils literal notranslate"><span class="pre">User-Agent</span></code> string sent to websites it visits.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id709">
<h3>0.6b4<a class="headerlink" href="#id709" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fix <code class="docutils literal notranslate"><span class="pre">register</span></code> not obeying name/version set by <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command, if
<code class="docutils literal notranslate"><span class="pre">egg_info</span></code> wasn’t explicitly run first on the same command line.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">--no-date</span></code> and <code class="docutils literal notranslate"><span class="pre">--no-svn-revision</span></code> options to <code class="docutils literal notranslate"><span class="pre">egg_info</span></code>
command, to allow suppressing tags configured in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>.</li>
<li>Fixed redundant warnings about missing <code class="docutils literal notranslate"><span class="pre">README</span></code> file(s); it should now
appear only if you are actually a source distribution.</li>
<li>Fix creating Python wrappers for non-Python scripts</li>
<li>Fix <code class="docutils literal notranslate"><span class="pre">ftp://</span></code> directory listing URLs from causing a crash when used in the
“Home page” or “Download URL” slots on PyPI.</li>
<li>Fix <code class="docutils literal notranslate"><span class="pre">sys.path_importer_cache</span></code> not being updated when an existing zipfile
or directory is deleted/overwritten.</li>
<li>Fix not recognizing HTML 404 pages from package indexes.</li>
<li>Allow <code class="docutils literal notranslate"><span class="pre">file://</span></code> URLs to be used as a package index.  URLs that refer to
directories will use an internally-generated directory listing if there is
no <code class="docutils literal notranslate"><span class="pre">index.html</span></code> file in the directory.</li>
<li>Allow external links in a package index to be specified using
<code class="docutils literal notranslate"><span class="pre">rel=&quot;homepage&quot;</span></code> or <code class="docutils literal notranslate"><span class="pre">rel=&quot;download&quot;</span></code>, without needing the old
PyPI-specific visible markup.</li>
<li>Suppressed warning message about possibly-misspelled project name, if an egg
or link for that project name has already been seen.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="b3">
<h3>0.6b3<a class="headerlink" href="#b3" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fix <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> not including files in subdirectories of <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code>.</li>
<li>Allow <code class="docutils literal notranslate"><span class="pre">.py</span></code> files found by the <code class="docutils literal notranslate"><span class="pre">include_package_data</span></code> option to be
automatically included. Remove duplicate data file matches if both
<code class="docutils literal notranslate"><span class="pre">include_package_data</span></code> and <code class="docutils literal notranslate"><span class="pre">package_data</span></code> are used to refer to the same
files.</li>
<li>Fix local <code class="docutils literal notranslate"><span class="pre">--find-links</span></code> eggs not being copied except with
<code class="docutils literal notranslate"><span class="pre">--always-copy</span></code>.</li>
<li>Fix sometimes not detecting local packages installed outside of “site”
directories.</li>
<li>Fix mysterious errors during initial <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> install, caused by
<code class="docutils literal notranslate"><span class="pre">ez_setup</span></code> trying to run <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> twice, due to a code fallthru
after deleting the egg from which it’s running.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="b2">
<h3>0.6b2<a class="headerlink" href="#b2" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Don’t install or update a <code class="docutils literal notranslate"><span class="pre">site.py</span></code> patch when installing to a
<code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> directory with <code class="docutils literal notranslate"><span class="pre">--multi-version</span></code>, unless an
<code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> file is already in use there.</li>
<li>Construct <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file paths in such a way that installing an egg whose
name begins with <code class="docutils literal notranslate"><span class="pre">import</span></code> doesn’t cause a syntax error.</li>
<li>Fixed a bogus warning message that wasn’t updated since the 0.5 versions.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="b1">
<h3>0.6b1<a class="headerlink" href="#b1" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Strip <code class="docutils literal notranslate"><span class="pre">module</span></code> from the end of compiled extension modules when computing
the name of a <code class="docutils literal notranslate"><span class="pre">.py</span></code> loader/wrapper.  (Python’s import machinery ignores
this suffix when searching for an extension module.)</li>
<li>Better ambiguity management: accept <code class="docutils literal notranslate"><span class="pre">#egg</span></code> name/version even if processing
what appears to be a correctly-named distutils file, and ignore <code class="docutils literal notranslate"><span class="pre">.egg</span></code>
files with no <code class="docutils literal notranslate"><span class="pre">-</span></code>, since valid Python <code class="docutils literal notranslate"><span class="pre">.egg</span></code> files always have a version
number (but Scheme eggs often don’t).</li>
<li>Support <code class="docutils literal notranslate"><span class="pre">file://</span></code> links to directories in <code class="docutils literal notranslate"><span class="pre">--find-links</span></code>, so that
easy_install can build packages from local source checkouts.</li>
<li>Added automatic retry for Sourceforge mirrors.  The new download process is
to first just try dl.sourceforge.net, then randomly select mirror IPs and
remove ones that fail, until something works.  The removed IPs stay removed
for the remainder of the run.</li>
<li>Ignore bdist_dumb distributions when looking at download URLs.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a11">
<h3>0.6a11<a class="headerlink" href="#a11" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul>
<li><p class="first">Added <code class="docutils literal notranslate"><span class="pre">test_loader</span></code> keyword to support custom test loaders</p>
</li>
<li><p class="first">Added <code class="docutils literal notranslate"><span class="pre">setuptools.file_finders</span></code> entry point group to allow implementing
revision control plugins.</p>
</li>
<li><p class="first">Added <code class="docutils literal notranslate"><span class="pre">--identity</span></code> option to <code class="docutils literal notranslate"><span class="pre">upload</span></code> command.</p>
</li>
<li><p class="first">Added <code class="docutils literal notranslate"><span class="pre">dependency_links</span></code> to allow specifying URLs for <code class="docutils literal notranslate"><span class="pre">--find-links</span></code>.</p>
</li>
<li><p class="first">Enhanced test loader to scan packages as well as modules, and call
<code class="docutils literal notranslate"><span class="pre">additional_tests()</span></code> if present to get non-unittest tests.</p>
</li>
<li><p class="first">Support namespace packages in conjunction with system packagers, by omitting
the installation of any <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files for namespace packages, and
adding a special <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file to create a working package in
<code class="docutils literal notranslate"><span class="pre">sys.modules</span></code>.</p>
</li>
<li><p class="first">Made <code class="docutils literal notranslate"><span class="pre">--single-version-externally-managed</span></code> automatic when <code class="docutils literal notranslate"><span class="pre">--root</span></code> is
used, so that most system packagers won’t require special support for
setuptools.</p>
</li>
<li><p class="first">Fixed <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code>, <code class="docutils literal notranslate"><span class="pre">tests_require</span></code>, etc. not using <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> or
other configuration files for their option defaults when installing, and
also made the install use <code class="docutils literal notranslate"><span class="pre">--multi-version</span></code> mode so that the project
directory doesn’t need to support .pth files.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> is now forcibly closed when any errors occur while reading
it. Previously, the file could be left open and the actual error would be
masked by problems trying to remove the open file on Windows systems.</p>
</li>
<li><p class="first">Process <code class="docutils literal notranslate"><span class="pre">dependency_links.txt</span></code> if found in a distribution, by adding the
URLs to the list for scanning.</p>
</li>
<li><p class="first">Use relative paths in <code class="docutils literal notranslate"><span class="pre">.pth</span></code> files when eggs are being installed to the
same directory as the <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file.  This maximizes portability of the
target directory when building applications that contain eggs.</p>
</li>
<li><p class="first">Added <code class="docutils literal notranslate"><span class="pre">easy_install-N.N</span></code> script(s) for convenience when using multiple
Python versions.</p>
</li>
<li><p class="first">Added automatic handling of installation conflicts.  Eggs are now shifted to
the front of sys.path, in an order consistent with where they came from,
making EasyInstall seamlessly co-operate with system package managers.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--delete-conflicting</span></code> and <code class="docutils literal notranslate"><span class="pre">--ignore-conflicts-at-my-risk</span></code> options
are now no longer necessary, and will generate warnings at the end of a
run if you use them.</p>
</li>
<li><p class="first">Don’t recursively traverse subdirectories given to <code class="docutils literal notranslate"><span class="pre">--find-links</span></code>.</p>
</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a10">
<h3>0.6a10<a class="headerlink" href="#a10" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fixed the <code class="docutils literal notranslate"><span class="pre">develop</span></code> command ignoring <code class="docutils literal notranslate"><span class="pre">--find-links</span></code>.</li>
<li>Added exhaustive testing of the install directory, including a spawn test
for <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file support, and directory writability/existence checks.  This
should virtually eliminate the need to set or configure <code class="docutils literal notranslate"><span class="pre">--site-dirs</span></code>.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">--prefix</span></code> option for more do-what-I-mean-ishness in the absence of
RTFM-ing.  :)</li>
<li>Enhanced <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> support so that you don’t have to put any eggs on it
manually to make it work.  <code class="docutils literal notranslate"><span class="pre">--multi-version</span></code> is no longer a silent
default; you must explicitly use it if installing to a non-PYTHONPATH,
non-“site” directory.</li>
<li>Expand <code class="docutils literal notranslate"><span class="pre">$variables</span></code> used in the <code class="docutils literal notranslate"><span class="pre">--site-dirs</span></code>, <code class="docutils literal notranslate"><span class="pre">--build-directory</span></code>,
<code class="docutils literal notranslate"><span class="pre">--install-dir</span></code>, and <code class="docutils literal notranslate"><span class="pre">--script-dir</span></code> options, whether on the command line
or in configuration files.</li>
<li>Improved SourceForge mirror processing to work faster and be less affected
by transient HTML changes made by SourceForge.</li>
<li>PyPI searches now use the exact spelling of requirements specified on the
command line or in a project’s <code class="docutils literal notranslate"><span class="pre">install_requires</span></code>.  Previously, a
normalized form of the name was used, which could lead to unnecessary
full-index searches when a project’s name had an underscore (<code class="docutils literal notranslate"><span class="pre">_</span></code>) in it.</li>
<li>EasyInstall can now download bare <code class="docutils literal notranslate"><span class="pre">.py</span></code> files and wrap them in an egg,
as long as you include an <code class="docutils literal notranslate"><span class="pre">#egg=name-version</span></code> suffix on the URL, or if
the <code class="docutils literal notranslate"><span class="pre">.py</span></code> file is listed as the “Download URL” on the project’s PyPI page.
This allows third parties to “package” trivial Python modules just by
linking to them (e.g. from within their own PyPI page or download links
page).</li>
<li>The <code class="docutils literal notranslate"><span class="pre">--always-copy</span></code> option now skips “system” and “development” eggs since
they can’t be reliably copied.  Note that this may cause EasyInstall to
choose an older version of a package than what you expected, or it may cause
downloading and installation of a fresh version of what’s already installed.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">--find-links</span></code> option previously scanned all supplied URLs and
directories as early as possible, but now only directories and direct
archive links are scanned immediately.  URLs are not retrieved unless a
package search was already going to go online due to a package not being
available locally, or due to the use of the <code class="docutils literal notranslate"><span class="pre">--update</span></code> or <code class="docutils literal notranslate"><span class="pre">-U</span></code> option.</li>
<li>Fixed the annoying <code class="docutils literal notranslate"><span class="pre">--help-commands</span></code> wart.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a9">
<h3>0.6a9<a class="headerlink" href="#a9" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>The <code class="docutils literal notranslate"><span class="pre">sdist</span></code> command no longer uses the traditional <code class="docutils literal notranslate"><span class="pre">MANIFEST</span></code> file to
create source distributions.  <code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> is still read and processed,
as are the standard defaults and pruning. But the manifest is built inside
the project’s <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> directory as <code class="docutils literal notranslate"><span class="pre">SOURCES.txt</span></code>, and it is rebuilt
every time the <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command is run.</li>
<li>Added the <code class="docutils literal notranslate"><span class="pre">include_package_data</span></code> keyword to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>, allowing you to
automatically include any package data listed in revision control or
<code class="docutils literal notranslate"><span class="pre">MANIFEST.in</span></code></li>
<li>Added the <code class="docutils literal notranslate"><span class="pre">exclude_package_data</span></code> keyword to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>, allowing you to
trim back files included via the <code class="docutils literal notranslate"><span class="pre">package_data</span></code> and
<code class="docutils literal notranslate"><span class="pre">include_package_data</span></code> options.</li>
<li>Fixed <code class="docutils literal notranslate"><span class="pre">--tag-svn-revision</span></code> not working when run from a source
distribution.</li>
<li>Added warning for namespace packages with missing <code class="docutils literal notranslate"><span class="pre">declare_namespace()</span></code></li>
<li>Added <code class="docutils literal notranslate"><span class="pre">tests_require</span></code> keyword to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>, so that e.g. packages
requiring <code class="docutils literal notranslate"><span class="pre">nose</span></code> to run unit tests can make this dependency optional
unless the <code class="docutils literal notranslate"><span class="pre">test</span></code> command is run.</li>
<li>Made all commands that use <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> respect its configuration
options, as this was causing some problems with <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">install</span></code>.</li>
<li>Added an <code class="docutils literal notranslate"><span class="pre">unpack_directory()</span></code> driver to <code class="docutils literal notranslate"><span class="pre">setuptools.archive_util</span></code>, so
that you can process a directory tree through a processing filter as if it
were a zipfile or tarfile.</li>
<li>Added an internal <code class="docutils literal notranslate"><span class="pre">install_egg_info</span></code> command to use as part of old-style
<code class="docutils literal notranslate"><span class="pre">install</span></code> operations, that installs an <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> directory with the
package.</li>
<li>Added a <code class="docutils literal notranslate"><span class="pre">--single-version-externally-managed</span></code> option to the <code class="docutils literal notranslate"><span class="pre">install</span></code>
command so that you can more easily wrap a “flat” egg in a system package.</li>
<li>Enhanced <code class="docutils literal notranslate"><span class="pre">bdist_rpm</span></code> so that it installs single-version eggs that
don’t rely on a <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file. The <code class="docutils literal notranslate"><span class="pre">--no-egg</span></code> option has been removed,
since all RPMs are now built in a more backwards-compatible format.</li>
<li>Support full roundtrip translation of eggs to and from <code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code>
format. Running <code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code> on a setuptools-based package wraps the
egg in an .exe that will safely install it as an egg (i.e., with metadata
and entry-point wrapper scripts), and <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> can turn the .exe
back into an <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file or directory and install it as such.</li>
<li>Fixed <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file processing picking up nested eggs (i.e. ones inside
“baskets”) when they weren’t explicitly listed in the <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file.</li>
<li>If more than one URL appears to describe the exact same distribution, prefer
the shortest one.  This helps to avoid “table of contents” CGI URLs like the
ones on effbot.org.</li>
<li>Quote arguments to python.exe (including python’s path) to avoid problems
when Python (or a script) is installed in a directory whose name contains
spaces on Windows.</li>
<li>Support full roundtrip translation of eggs to and from <code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code>
format.  Running <code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code> on a setuptools-based package wraps the
egg in an .exe that will safely install it as an egg (i.e., with metadata
and entry-point wrapper scripts), and <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> can turn the .exe
back into an <code class="docutils literal notranslate"><span class="pre">.egg</span></code> file or directory and install it as such.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a8">
<h3>0.6a8<a class="headerlink" href="#a8" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fixed some problems building extensions when Pyrex was installed, especially
with Python 2.4 and/or packages using SWIG.</li>
<li>Made <code class="docutils literal notranslate"><span class="pre">develop</span></code> command accept all the same options as <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>,
and use the <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> command’s configuration settings as defaults.</li>
<li>Made <code class="docutils literal notranslate"><span class="pre">egg_info</span> <span class="pre">--tag-svn-revision</span></code> fall back to extracting the revision
number from <code class="docutils literal notranslate"><span class="pre">PKG-INFO</span></code> in case it is being run on a source distribution of
a snapshot taken from a Subversion-based project.</li>
<li>Automatically detect <code class="docutils literal notranslate"><span class="pre">.dll</span></code>, <code class="docutils literal notranslate"><span class="pre">.so</span></code> and <code class="docutils literal notranslate"><span class="pre">.dylib</span></code> files that are being
installed as data, adding them to <code class="docutils literal notranslate"><span class="pre">native_libs.txt</span></code> automatically.</li>
<li>Fixed some problems with fresh checkouts of projects that don’t include
<code class="docutils literal notranslate"><span class="pre">.egg-info/PKG-INFO</span></code> under revision control and put the project’s source
code directly in the project directory. If such a package had any
requirements that get processed before the <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command can be run,
the setup scripts would fail with a “Missing ‘Version:’ header and/or
PKG-INFO file” error, because the egg runtime interpreted the unbuilt
metadata in a directory on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> (i.e. the current directory) as
being a corrupted egg. Setuptools now monkeypatches the distribution
metadata cache to pretend that the egg has valid version information, until
it has a chance to make it actually be so (via the <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command).</li>
<li>Update for changed SourceForge mirror format</li>
<li>Fixed not installing dependencies for some packages fetched via Subversion</li>
<li>Fixed dependency installation with <code class="docutils literal notranslate"><span class="pre">--always-copy</span></code> not using the same
dependency resolution procedure as other operations.</li>
<li>Fixed not fully removing temporary directories on Windows, if a Subversion
checkout left read-only files behind</li>
<li>Fixed some problems building extensions when Pyrex was installed, especially
with Python 2.4 and/or packages using SWIG.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a7">
<h3>0.6a7<a class="headerlink" href="#a7" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fixed not being able to install Windows script wrappers using Python 2.3</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a6">
<h3>0.6a6<a class="headerlink" href="#a6" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added support for “traditional” PYTHONPATH-based non-root installation, and
also the convenient <code class="docutils literal notranslate"><span class="pre">virtual-python.py</span></code> script, based on a contribution
by Ian Bicking.  The setuptools egg now contains a hacked <code class="docutils literal notranslate"><span class="pre">site</span></code> module
that makes the PYTHONPATH-based approach work with .pth files, so that you
can get the full EasyInstall feature set on such installations.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">--no-deps</span></code> and <code class="docutils literal notranslate"><span class="pre">--allow-hosts</span></code> options.</li>
<li>Improved Windows <code class="docutils literal notranslate"><span class="pre">.exe</span></code> script wrappers so that the script can have the
same name as a module without confusing Python.</li>
<li>Changed dependency processing so that it’s breadth-first, allowing a
depender’s preferences to override those of a dependee, to prevent conflicts
when a lower version is acceptable to the dependee, but not the depender.
Also, ensure that currently installed/selected packages aren’t given
precedence over ones desired by a package being installed, which could
cause conflict errors.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a5">
<h3>0.6a5<a class="headerlink" href="#a5" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fixed missing gui/cli .exe files in distribution. Fixed bugs in tests.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a3">
<h3>0.6a3<a class="headerlink" href="#a3" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added <code class="docutils literal notranslate"><span class="pre">gui_scripts</span></code> entry point group to allow installing GUI scripts
on Windows and other platforms.  (The special handling is only for Windows;
other platforms are treated the same as for <code class="docutils literal notranslate"><span class="pre">console_scripts</span></code>.)</li>
<li>Improved error message when trying to use old ways of running
<code class="docutils literal notranslate"><span class="pre">easy_install</span></code>.  Removed the ability to run via <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span></code> or by
running <code class="docutils literal notranslate"><span class="pre">easy_install.py</span></code>; <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> is the command to run on all
supported platforms.</li>
<li>Improved wrapper script generation and runtime initialization so that a
VersionConflict doesn’t occur if you later install a competing version of a
needed package as the default version of that package.</li>
<li>Fixed a problem parsing version numbers in <code class="docutils literal notranslate"><span class="pre">#egg=</span></code> links.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a2">
<h3>0.6a2<a class="headerlink" href="#a2" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added <code class="docutils literal notranslate"><span class="pre">console_scripts</span></code> entry point group to allow installing scripts
without the need to create separate script files. On Windows, console
scripts get an <code class="docutils literal notranslate"><span class="pre">.exe</span></code> wrapper so you can just type their name. On other
platforms, the scripts are written without a file extension.</li>
<li>EasyInstall can now install “console_scripts” defined by packages that use
<code class="docutils literal notranslate"><span class="pre">setuptools</span></code> and define appropriate entry points.  On Windows, console
scripts get an <code class="docutils literal notranslate"><span class="pre">.exe</span></code> wrapper so you can just type their name.  On other
platforms, the scripts are installed without a file extension.</li>
<li>Using <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">easy_install</span></code> or running <code class="docutils literal notranslate"><span class="pre">easy_install.py</span></code> is now
DEPRECATED, since an <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> wrapper is now available on all
platforms.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a1">
<h3>0.6a1<a class="headerlink" href="#a1" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added support for building “old-style” RPMs that don’t install an egg for
the target package, using a <code class="docutils literal notranslate"><span class="pre">--no-egg</span></code> option.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">build_ext</span></code> command now works better when using the <code class="docutils literal notranslate"><span class="pre">--inplace</span></code>
option and multiple Python versions. It now makes sure that all extensions
match the current Python version, even if newer copies were built for a
different Python version.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">upload</span></code> command no longer attaches an extra <code class="docutils literal notranslate"><span class="pre">.zip</span></code> when uploading
eggs, as PyPI now supports egg uploads without trickery.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">ez_setup</span></code> script/module now displays a warning before downloading
the setuptools egg, and attempts to check the downloaded egg against an
internal MD5 checksum table.</li>
<li>Fixed the <code class="docutils literal notranslate"><span class="pre">--tag-svn-revision</span></code> option of <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> not finding the
latest revision number; it was using the revision number of the directory
containing <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>, not the highest revision number in the project.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">eager_resources</span></code> setup argument</li>
<li>The <code class="docutils literal notranslate"><span class="pre">sdist</span></code> command now recognizes Subversion “deleted file” entries and
does not include them in source distributions.</li>
<li><code class="docutils literal notranslate"><span class="pre">setuptools</span></code> now embeds itself more thoroughly into the distutils, so that
other distutils extensions (e.g. py2exe, py2app) will subclass setuptools’
versions of things, rather than the native distutils ones.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">entry_points</span></code> and <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> arguments to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>;
<code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> allows you to automatically find and download packages
that are needed in order to <em>build</em> your project (as opposed to running it).</li>
<li><code class="docutils literal notranslate"><span class="pre">setuptools</span></code> now finds its commands, <code class="docutils literal notranslate"><span class="pre">setup()</span></code> argument validators, and
metadata writers using entry points, so that they can be extended by
third-party packages. See <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#creating-distutils-extensions">Creating distutils Extensions</a>
for more details.</li>
<li>The vestigial <code class="docutils literal notranslate"><span class="pre">depends</span></code> command has been removed. It was never finished
or documented, and never would have worked without EasyInstall - which it
pre-dated and was never compatible with.</li>
<li>EasyInstall now does MD5 validation of downloads from PyPI, or from any link
that has an “#md5=…” trailer with a 32-digit lowercase hex md5 digest.</li>
<li>EasyInstall now handles symlinks in target directories by removing the link,
rather than attempting to overwrite the link’s destination.  This makes it
easier to set up an alternate Python “home” directory (as described in
the Non-Root Installation section of the docs).</li>
<li>Added support for handling MacOS platform information in <code class="docutils literal notranslate"><span class="pre">.egg</span></code> filenames,
based on a contribution by Kevin Dangoor.  You may wish to delete and
reinstall any eggs whose filename includes “darwin” and “Power_Macintosh”,
because the format for this platform information has changed so that minor
OS X upgrades (such as 10.4.1 to 10.4.2) do not cause eggs built with a
previous OS version to become obsolete.</li>
<li>easy_install’s dependency processing algorithms have changed.  When using
<code class="docutils literal notranslate"><span class="pre">--always-copy</span></code>, it now ensures that dependencies are copied too.  When
not using <code class="docutils literal notranslate"><span class="pre">--always-copy</span></code>, it tries to use a single resolution loop,
rather than recursing.</li>
<li>Fixed installing extra <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> or <code class="docutils literal notranslate"><span class="pre">.pyo</span></code> files for scripts with <code class="docutils literal notranslate"><span class="pre">.py</span></code>
extensions.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">--site-dirs</span></code> option to allow adding custom “site” directories.
Made <code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> work in platform-specific alternate site
directories (e.g. <code class="docutils literal notranslate"><span class="pre">~/Library/Python/2.x/site-packages</span></code> on Mac OS X).</li>
<li>If you manually delete the current version of a package, the next run of
EasyInstall against the target directory will now remove the stray entry
from the <code class="docutils literal notranslate"><span class="pre">easy-install.pth</span></code> file.</li>
<li>EasyInstall now recognizes URLs with a <code class="docutils literal notranslate"><span class="pre">#egg=project_name</span></code> fragment ID
as pointing to the named project’s source checkout.  Such URLs have a lower
match precedence than any other kind of distribution, so they’ll only be
used if they have a higher version number than any other available
distribution, or if you use the <code class="docutils literal notranslate"><span class="pre">--editable</span></code> option.  The <code class="docutils literal notranslate"><span class="pre">#egg</span></code>
fragment can contain a version if it’s formatted as <code class="docutils literal notranslate"><span class="pre">#egg=proj-ver</span></code>,
where <code class="docutils literal notranslate"><span class="pre">proj</span></code> is the project name, and <code class="docutils literal notranslate"><span class="pre">ver</span></code> is the version number.  You
<em>must</em> use the format for these values that the <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> command uses;
i.e., all non-alphanumeric runs must be condensed to single underscore
characters.</li>
<li>Added the <code class="docutils literal notranslate"><span class="pre">--editable</span></code> option; see Editing and Viewing Source Packages
in the docs.  Also, slightly changed the behavior of the
<code class="docutils literal notranslate"><span class="pre">--build-directory</span></code> option.</li>
<li>Fixed the setup script sandbox facility not recognizing certain paths as
valid on case-insensitive platforms.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a12">
<h3>0.5a12<a class="headerlink" href="#a12" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>The zip-safety scanner now checks for modules that might be used with
<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span></code>, and marks them as unsafe for zipping, since Python 2.4 can’t
handle <code class="docutils literal notranslate"><span class="pre">-m</span></code> on zipped modules.</li>
<li>Fix <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">easy_install</span></code> not working due to setuptools being installed
as a zipfile.  Update safety scanner to check for modules that might be used
as <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span></code> scripts.</li>
<li>Misc. fixes for win32.exe support, including changes to support Python 2.4’s
changed <code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code> format.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id710">
<h3>0.5a11<a class="headerlink" href="#id710" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fix breakage of the “develop” command that was caused by the addition of
<code class="docutils literal notranslate"><span class="pre">--always-unzip</span></code> to the <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> command.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id711">
<h3>0.5a10<a class="headerlink" href="#id711" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Put the <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> module back in as a module, as it’s needed for
<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span></code> to run it!</li>
<li>Allow <code class="docutils literal notranslate"><span class="pre">--find-links/-f</span></code> to accept local directories or filenames as well
as URLs.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id712">
<h3>0.5a9<a class="headerlink" href="#id712" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Include <code class="docutils literal notranslate"><span class="pre">svn:externals</span></code> directories in source distributions as well as
normal subversion-controlled files and directories.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">exclude=patternlist</span></code> option to <code class="docutils literal notranslate"><span class="pre">setuptools.find_packages()</span></code></li>
<li>Changed –tag-svn-revision to include an “r” in front of the revision number
for better readability.</li>
<li>Added ability to build eggs without including source files (except for any
scripts, of course), using the <code class="docutils literal notranslate"><span class="pre">--exclude-source-files</span></code> option to
<code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code>.</li>
<li><code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">install</span></code> now automatically detects when an “unmanaged” package
or module is going to be on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> ahead of a package being installed,
thereby preventing the newer version from being imported. If this occurs,
a warning message is output to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>, but installation proceeds
anyway. The warning message informs the user what files or directories
need deleting, and advises them they can also use EasyInstall (with the
<code class="docutils literal notranslate"><span class="pre">--delete-conflicting</span></code> option) to do it automatically.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command now adds a <code class="docutils literal notranslate"><span class="pre">top_level.txt</span></code> file to the metadata
directory that lists all top-level modules and packages in the distribution.
This is used by the <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> command to find possibly-conflicting
“unmanaged” packages when installing the distribution.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">zip_safe</span></code> and <code class="docutils literal notranslate"><span class="pre">namespace_packages</span></code> arguments to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>.
Added package analysis to determine zip-safety if the <code class="docutils literal notranslate"><span class="pre">zip_safe</span></code> flag
is not given, and advise the author regarding what code might need changing.</li>
<li>Fixed the swapped <code class="docutils literal notranslate"><span class="pre">-d</span></code> and <code class="docutils literal notranslate"><span class="pre">-b</span></code> options of <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code>.</li>
<li>EasyInstall now automatically detects when an “unmanaged” package or
module is going to be on <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> ahead of a package you’re installing,
thereby preventing the newer version from being imported.  By default, it
will abort installation to alert you of the problem, but there are also
new options (<code class="docutils literal notranslate"><span class="pre">--delete-conflicting</span></code> and <code class="docutils literal notranslate"><span class="pre">--ignore-conflicts-at-my-risk</span></code>)
available to change the default behavior.  (Note: this new feature doesn’t
take effect for egg files that were built with older <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>
versions, because they lack the new metadata file required to implement it.)</li>
<li>The <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> distutils command now uses <code class="docutils literal notranslate"><span class="pre">DistutilsError</span></code> as its
base error type for errors that should just issue a message to stderr and
exit the program without a traceback.</li>
<li>EasyInstall can now be given a path to a directory containing a setup
script, and it will attempt to build and install the package there.</li>
<li>EasyInstall now performs a safety analysis on module contents to determine
whether a package is likely to run in zipped form, and displays
information about what modules may be doing introspection that would break
when running as a zipfile.</li>
<li>Added the <code class="docutils literal notranslate"><span class="pre">--always-unzip/-Z</span></code> option, to force unzipping of packages that
would ordinarily be considered safe to unzip, and changed the meaning of
<code class="docutils literal notranslate"><span class="pre">--zip-ok/-z</span></code> to “always leave everything zipped”.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id713">
<h3>0.5a8<a class="headerlink" href="#id713" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>The “egg_info” command now always sets the distribution metadata to “safe”
forms of the distribution name and version, so that distribution files will
be generated with parseable names (i.e., ones that don’t include ‘-‘ in the
name or version). Also, this means that if you use the various <code class="docutils literal notranslate"><span class="pre">--tag</span></code>
options of “egg_info”, any distributions generated will use the tags in the
version, not just egg distributions.</li>
<li>Added support for defining command aliases in distutils configuration files,
under the “[aliases]” section. To prevent recursion and to allow aliases to
call the command of the same name, a given alias can be expanded only once
per command-line invocation. You can define new aliases with the “alias”
command, either for the local, global, or per-user configuration.</li>
<li>Added “rotate” command to delete old distribution files, given a set of
patterns to match and the number of files to keep.  (Keeps the most
recently-modified distribution files matching each pattern.)</li>
<li>Added “saveopts” command that saves all command-line options for the current
invocation to the local, global, or per-user configuration file. Useful for
setting defaults without having to hand-edit a configuration file.</li>
<li>Added a “setopt” command that sets a single option in a specified distutils
configuration file.</li>
<li>There is now a separate documentation page for setuptools; revision
history that’s not specific to EasyInstall has been moved to that page.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id714">
<h3>0.5a7<a class="headerlink" href="#id714" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added “upload” support for egg and source distributions, including a bug
fix for “upload” and a temporary workaround for lack of .egg support in
PyPI.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id715">
<h3>0.5a6<a class="headerlink" href="#id715" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Beefed up the “sdist” command so that if you don’t have a MANIFEST.in, it
will include all files under revision control (CVS or Subversion) in the
current directory, and it will regenerate the list every time you create a
source distribution, not just when you tell it to. This should make the
default “do what you mean” more often than the distutils’ default behavior
did, while still retaining the old behavior in the presence of MANIFEST.in.</li>
<li>Fixed the “develop” command always updating .pth files, even if you
specified <code class="docutils literal notranslate"><span class="pre">-n</span></code> or <code class="docutils literal notranslate"><span class="pre">--dry-run</span></code>.</li>
<li>Slightly changed the format of the generated version when you use
<code class="docutils literal notranslate"><span class="pre">--tag-build</span></code> on the “egg_info” command, so that you can make tagged
revisions compare <em>lower</em> than the version specified in setup.py (e.g. by
using <code class="docutils literal notranslate"><span class="pre">--tag-build=dev</span></code>).</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id716">
<h3>0.5a5<a class="headerlink" href="#id716" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added <code class="docutils literal notranslate"><span class="pre">develop</span></code> command to <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>-based packages. This command
installs an <code class="docutils literal notranslate"><span class="pre">.egg-link</span></code> pointing to the package’s source directory, and
script wrappers that <code class="docutils literal notranslate"><span class="pre">execfile()</span></code> the source versions of the package’s
scripts. This lets you put your development checkout(s) on sys.path without
having to actually install them.  (To uninstall the link, use
use <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">develop</span> <span class="pre">--uninstall</span></code>.)</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">egg_info</span></code> command to <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>-based packages. This command
just creates or updates the “projectname.egg-info” directory, without
building an egg.  (It’s used by the <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code>, <code class="docutils literal notranslate"><span class="pre">test</span></code>, and <code class="docutils literal notranslate"><span class="pre">develop</span></code>
commands.)</li>
<li>Enhanced the <code class="docutils literal notranslate"><span class="pre">test</span></code> command so that it doesn’t install the package, but
instead builds any C extensions in-place, updates the <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code>
metadata, adds the source directory to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>, and runs the tests
directly on the source. This avoids an “unmanaged” installation of the
package to <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> or elsewhere.</li>
<li>Made <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> a standard <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> command, moving it from
the <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> module to <code class="docutils literal notranslate"><span class="pre">setuptools.command.easy_install</span></code>. Note
that if you were importing or extending it, you must now change your imports
accordingly.  <code class="docutils literal notranslate"><span class="pre">easy_install.py</span></code> is still installed as a script, but not as
a module.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a4">
<h3>0.5a4<a class="headerlink" href="#a4" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Setup scripts using setuptools can now list their dependencies directly in
the setup.py file, without having to manually create a <code class="docutils literal notranslate"><span class="pre">depends.txt</span></code> file.
The <code class="docutils literal notranslate"><span class="pre">install_requires</span></code> and <code class="docutils literal notranslate"><span class="pre">extras_require</span></code> arguments to <code class="docutils literal notranslate"><span class="pre">setup()</span></code>
are used to create a dependencies file automatically. If you are manually
creating <code class="docutils literal notranslate"><span class="pre">depends.txt</span></code> right now, please switch to using these setup
arguments as soon as practical, because <code class="docutils literal notranslate"><span class="pre">depends.txt</span></code> support will be
removed in the 0.6 release cycle. For documentation on the new arguments,
see the <code class="docutils literal notranslate"><span class="pre">setuptools.dist.Distribution</span></code> class.</li>
<li>Setup scripts using setuptools now always install using <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>
internally, for ease of uninstallation and upgrading.</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">--always-copy/-a</span></code> option to always copy needed packages to the
installation directory, even if they’re already present elsewhere on
sys.path. (In previous versions, this was the default behavior, but now
you must request it.)</li>
<li>Added <code class="docutils literal notranslate"><span class="pre">--upgrade/-U</span></code> option to force checking PyPI for latest available
version(s) of all packages requested by name and version, even if a matching
version is available locally.</li>
<li>Added automatic installation of dependencies declared by a distribution
being installed.  These dependencies must be listed in the distribution’s
<code class="docutils literal notranslate"><span class="pre">EGG-INFO</span></code> directory, so the distribution has to have declared its
dependencies by using setuptools.  If a package has requirements it didn’t
declare, you’ll still have to deal with them yourself.  (E.g., by asking
EasyInstall to find and install them.)</li>
<li>Added the <code class="docutils literal notranslate"><span class="pre">--record</span></code> option to <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> for the benefit of tools
that run <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">install</span> <span class="pre">--record=filename</span></code> on behalf of another
packaging system.)</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id717">
<h3>0.5a3<a class="headerlink" href="#id717" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fixed not setting script permissions to allow execution.</li>
<li>Improved sandboxing so that setup scripts that want a temporary directory
(e.g. pychecker) can still run in the sandbox.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id718">
<h3>0.5a2<a class="headerlink" href="#id718" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Fix stupid stupid refactoring-at-the-last-minute typos.  :(</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id719">
<h3>0.5a1<a class="headerlink" href="#id719" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul>
<li><p class="first">Added support for “self-installation” bootstrapping. Packages can now
include <code class="docutils literal notranslate"><span class="pre">ez_setup.py</span></code> in their source distribution, and add the following
to their <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>, in order to automatically bootstrap installation of
setuptools as part of their setup process:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">ez_setup</span> <span class="k">import</span> <span class="n">use_setuptools</span>
<span class="n">use_setuptools</span><span class="p">()</span>

<span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span>
<span class="c1"># etc...</span>
</pre></div>
</div>
</li>
<li><p class="first">Added support for converting <code class="docutils literal notranslate"><span class="pre">.win32.exe</span></code> installers to eggs on the fly.
EasyInstall will now recognize such files by name and install them.</p>
</li>
<li><p class="first">Fixed a problem with picking the “best” version to install (versions were
being sorted as strings, rather than as parsed values)</p>
</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id720">
<h3>0.4a4<a class="headerlink" href="#id720" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added support for the distutils “verbose/quiet” and “dry-run” options, as
well as the “optimize” flag.</li>
<li>Support downloading packages that were uploaded to PyPI (by scanning all
links on package pages, not just the homepage/download links).</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id721">
<h3>0.4a3<a class="headerlink" href="#id721" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Add progress messages to the search/download process so that you can tell
what URLs it’s reading to find download links.  (Hopefully, this will help
people report out-of-date and broken links to package authors, and to tell
when they’ve asked for a package that doesn’t exist.)</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id722">
<h3>0.4a2<a class="headerlink" href="#id722" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added <code class="docutils literal notranslate"><span class="pre">ez_setup.py</span></code> installer/bootstrap script to make initial setuptools
installation easier, and to allow distributions using setuptools to avoid
having to include setuptools in their source distribution.</li>
<li>All downloads are now managed by the <code class="docutils literal notranslate"><span class="pre">PackageIndex</span></code> class (which is now
subclassable and replaceable), so that embedders can more easily override
download logic, give download progress reports, etc. The class has also
been moved to the new <code class="docutils literal notranslate"><span class="pre">setuptools.package_index</span></code> module.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">Installer</span></code> class no longer handles downloading, manages a temporary
directory, or tracks the <code class="docutils literal notranslate"><span class="pre">zip_ok</span></code> option. Downloading is now handled
by <code class="docutils literal notranslate"><span class="pre">PackageIndex</span></code>, and <code class="docutils literal notranslate"><span class="pre">Installer</span></code> has become an <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>
command class based on <code class="docutils literal notranslate"><span class="pre">setuptools.Command</span></code>.</li>
<li>There is a new <code class="docutils literal notranslate"><span class="pre">setuptools.sandbox.run_setup()</span></code> API to invoke a setup
script in a directory sandbox, and a new <code class="docutils literal notranslate"><span class="pre">setuptools.archive_util</span></code> module
with an <code class="docutils literal notranslate"><span class="pre">unpack_archive()</span></code> API. These were split out of EasyInstall to
allow reuse by other tools and applications.</li>
<li><code class="docutils literal notranslate"><span class="pre">setuptools.Command</span></code> now supports reinitializing commands using keyword
arguments to set/reset options. Also, <code class="docutils literal notranslate"><span class="pre">Command</span></code> subclasses can now set
their <code class="docutils literal notranslate"><span class="pre">command_consumes_arguments</span></code> attribute to <code class="docutils literal notranslate"><span class="pre">True</span></code> in order to
receive an <code class="docutils literal notranslate"><span class="pre">args</span></code> option containing the rest of the command line.</li>
<li>Added support for installing scripts</li>
<li>Added support for setting options via distutils configuration files, and
using distutils’ default options as a basis for EasyInstall’s defaults.</li>
<li>Renamed <code class="docutils literal notranslate"><span class="pre">--scan-url/-s</span></code> to <code class="docutils literal notranslate"><span class="pre">--find-links/-f</span></code> to free up <code class="docutils literal notranslate"><span class="pre">-s</span></code> for the
script installation directory option.</li>
<li>Use <code class="docutils literal notranslate"><span class="pre">urllib2</span></code> instead of <code class="docutils literal notranslate"><span class="pre">urllib</span></code>, to allow use of <code class="docutils literal notranslate"><span class="pre">https:</span></code> URLs if
Python includes SSL support.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id723">
<h3>0.4a1<a class="headerlink" href="#id723" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added <code class="docutils literal notranslate"><span class="pre">--scan-url</span></code> and <code class="docutils literal notranslate"><span class="pre">--index-url</span></code> options, to scan download pages
and search PyPI for needed packages.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id724">
<h3>0.3a4<a class="headerlink" href="#id724" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Restrict <code class="docutils literal notranslate"><span class="pre">--build-directory=DIR/-b</span> <span class="pre">DIR</span></code> option to only be used with single
URL installs, to avoid running the wrong setup.py.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id725">
<h3>0.3a3<a class="headerlink" href="#id725" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added <code class="docutils literal notranslate"><span class="pre">--build-directory=DIR/-b</span> <span class="pre">DIR</span></code> option.</li>
<li>Added “installation report” that explains how to use ‘require()’ when doing
a multiversion install or alternate installation directory.</li>
<li>Added SourceForge mirror auto-select (Contributed by Ian Bicking)</li>
<li>Added “sandboxing” that stops a setup script from running if it attempts to
write to the filesystem outside of the build area</li>
<li>Added more workarounds for packages with quirky <code class="docutils literal notranslate"><span class="pre">install_data</span></code> hacks</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id726">
<h3>0.3a2<a class="headerlink" href="#id726" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Added new options to <code class="docutils literal notranslate"><span class="pre">bdist_egg</span></code> to allow tagging the egg’s version number
with a subversion revision number, the current date, or an explicit tag
value. Run <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">bdist_egg</span> <span class="pre">--help</span></code> to get more information.</li>
<li>Added subversion download support for <code class="docutils literal notranslate"><span class="pre">svn:</span></code> and <code class="docutils literal notranslate"><span class="pre">svn+</span></code> URLs, as well as
automatic recognition of HTTP subversion URLs (Contributed by Ian Bicking)</li>
<li>Misc. bug fixes</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="id727">
<h3>0.3a1<a class="headerlink" href="#id727" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li>Initial release.</li>
</ul>
</div></blockquote>
</div>
</div>
<div class="section" id="credits">
<h2>Credits<a class="headerlink" href="#credits" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>The original design for the <code class="docutils literal notranslate"><span class="pre">.egg</span></code> format and the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> API was
co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first
version of <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>, and supplied the macOS operating system version
compatibility algorithm.</li>
<li>Ian Bicking implemented many early “creature comfort” features of
easy_install, including support for downloading via Sourceforge and
Subversion repositories. Ian’s comments on the Web-SIG about WSGI
application deployment also inspired the concept of “entry points” in eggs,
and he has given talks at PyCon and elsewhere to inform and educate the
community about eggs and setuptools.</li>
<li>Jim Fulton contributed time and effort to build automated tests of various
aspects of <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>, and supplied the doctests for the command-line
<code class="docutils literal notranslate"><span class="pre">.exe</span></code> wrappers on Windows.</li>
<li>Phillip J. Eby is the seminal author of setuptools, and
first proposed the idea of an importable binary distribution format for
Python application plug-ins.</li>
<li>Significant parts of the implementation of setuptools were funded by the Open
Source Applications Foundation, to provide a plug-in infrastructure for the
Chandler PIM application. In addition, many OSAF staffers (such as Mike
“Code Bear” Taylor) contributed their time and stress as guinea pigs for the
use of eggs and setuptools, even before eggs were “cool”.  (Thanks, guys!)</li>
<li>Tarek Ziadé is the principal author of the Distribute fork, which
re-invigorated the community on the project, encouraged renewed innovation,
and addressed many defects.</li>
<li>Jason R. Coombs performed the merge with Distribute, maintaining the
project for several years in coordination with the Python Packaging
Authority (PyPA).</li>
</ul>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper"><h3 class="donation">For Enterprise</h3>

<p>
Professionally-supported setuptools is available with the
<a href="https://tidelift.com/subscription/pkg/pypi-setuptools?utm_source=pypi-setuptools&utm_medium=referral">Tidelift Subscription</a>.
</p>

<h3>Download</h3>

<p>Current version: <b>46.1.3</b></p>
<p>Get Setuptools from the <a href="https://pypi.org/project/setuptools/"> Python Package Index</a>

<h3>Questions? Suggestions? Contributions?</h3>

<p>Visit the <a href="https://github.com/pypa/setuptools">Project page</a> </p>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="nav-item nav-item-0"><a href="index.html#document-index">setuptools 46.1.3 documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright Python Packaging Authority.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
    </div>
  </body>
</html>